Ditinjau 2026-11-10 · Versi API 2026-11-09 · Baca Markdown
Mengunggah dan menyimpan media
Byte media berpindah langsung ke penyimpanan objek privat sementara. REST dan MCP
mengembalikan instruksi unggahan; keduanya tidak menerima konten berkas biner dalam JSON alat.
Penyimpanan harus dikonfigurasi pada deployment atau pembuatan unggahan akan
mengembalikan provider_unavailable.
Siklus hidup unggahan
- Panggil
POST /api/v1/media/upload-intentsdengan nama berkas, MIME yang dinyatakan, dan jumlah byte. SimpanassetIddansessionIdyang dikembalikan sebagai identitas terpisah. - Periksa
method. Untukpresigned_put, unggah seluruh berkas keuploadUrlmenggunakan header yang dikembalikan. Untukmultipart_initiated, pecah denganpartSizeBytes, unggah setiap bagian bernomor ke URL yang dikembalikan dan pertahankan tanda terima ETag. Jangan pernah menambahkan bearer key AiVideoEditor ke permintaan penyimpanan. - Finalisasi di
POST /api/v1/media/{assetId}/finalizedengansessionIddan, untuk multipart,multipart.partsyang memuat setiappartNumberdanetag. - Gunakan ID aset yang sudah difinalisasi di
mediaIdsdraf. Intent unggahan saja tidak membuat aset dapat diterbitkan.
Server mengamati byte dan format aktual pada salinan akhir yang tidak dapat diubah. Ukuran/MIME yang dinyatakan adalah masukan pencadangan, bukan bukti validitas berkas. Keluarga dasar yang didukung adalah JPEG, PNG, dan MP4; tujuan individual dapat memberlakukan batas lebih ketat. Ukuran berkas maksimum saat ini adalah 500 MiB (524.288.000 byte). Berkas sebesar 50 MiB atau lebih menggunakan multipart, biasanya dengan bagian 16 MiB. Selalu ikuti ukuran, URL, dan kedaluwarsa yang dikembalikan alih-alih menurunkannya dari nilai default ini.
{
"sessionId": "<session UUID from upload-intents>",
"multipart": {
"parts": [
{ "partNumber": 1, "etag": "<ETag returned by storage>" }
]
}
}
Ini adalah ilustrasi bentuk multipart; sertakan setiap bagian aktual. Finalisasi
single-PUT hanya mengirim sessionId. Beri setiap mutasi API baru
Idempotency-Key sendiri; pertahankan untuk percobaan ulang identik yang aman.
Melanjutkan atau mengabaikan
URL bertanda tangan yang kedaluwarsa bukan alamat media permanen. Minta URL bagian multipart
baru dengan POST /media/{id}/upload-parts menggunakan fromPart dan toPart (rentang inklusif
hingga maksimum 64 bagian). Lihat referensi API untuk bentuk permintaan
berbatas. Jangan mengunggah ulang bagian yang sudah selesai secara tidak perlu atau menyelesaikan
perakitan multipart langsung melalui penyimpanan: finalisasi dikendalikan server.
Gunakan POST /media/{id}/abandon saat membatalkan unggahan yang belum selesai. Ini melepaskan
cadangannya melalui alur kerja pembersihan bersama. Kedaluwarsa sesi atau keadaan multipart
yang sudah terpakai mungkin memerlukan intent baru; jangan menduga-duga kunci objek penyimpanan.
Penyimpanan sementara
GET /media/{id} mengembalikan status dan informasi deleteAfter dinamis, bukan
URL publik permanen. Penggunaan terjadwal dan yang sedang berjalan melindungi media selama pekerjaan.
Kebijakan bawaan menyimpan media draf yang tidak terpakai selama 14 hari, media yang selesai
72 jam, dan pekerjaan gagal atau ambigu selama 7 hari setelah percobaan terkait. Penyimpanan
aktual bergantung pada semua referensi yang tersisa; deleteAfter bisa null.
Simpan berkas asli. Jika media kedaluwarsa atau sedang dihapus, unggah ulang sebelum menerbitkan.