AiVideoEditor
Mulai gratis
Menu

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

  1. Panggil POST /api/v1/media/upload-intents dengan nama berkas, MIME yang dinyatakan, dan jumlah byte. Simpan assetId dan sessionId yang dikembalikan sebagai identitas terpisah.
  2. Periksa method. Untuk presigned_put, unggah seluruh berkas ke uploadUrl menggunakan header yang dikembalikan. Untuk multipart_initiated, pecah dengan partSizeBytes, unggah setiap bagian bernomor ke URL yang dikembalikan dan pertahankan tanda terima ETag. Jangan pernah menambahkan bearer key AiVideoEditor ke permintaan penyimpanan.
  3. Finalisasi di POST /api/v1/media/{assetId}/finalize dengan sessionId dan, untuk multipart, multipart.parts yang memuat setiap partNumber dan etag.
  4. Gunakan ID aset yang sudah difinalisasi di mediaIds draf. 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.