curl --request POST \
--url https://api.apimart.ai/v1/uploads/videos \
--header 'Authorization: Bearer <token>' \
--form 'file=@/path/to/reference.mp4'
import requests
with open("reference.mp4", "rb") as file:
response = requests.post(
"https://api.apimart.ai/v1/uploads/videos",
headers={"Authorization": "Bearer <token>"},
files={"file": file}
)
response.raise_for_status()
result = response.json()
print(result["url"])
const input = document.querySelector('input[type="file"]');
const file = input?.files?.[0];
if (!file) throw new Error("Select a file first");
const formData = new FormData();
formData.append("file", file, file.name);
const response = await fetch("https://api.apimart.ai/v1/uploads/videos", {
method: "POST",
headers: { Authorization: "Bearer <token>" },
body: formData
});
const result = await response.json();
if (!response.ok) {
throw new Error(result.error?.message ?? `HTTP ${response.status}`);
}
console.log(result.url);
{
"url": "https://cdn.example/uploads/reference.mp4",
"filename": "reference.mp4",
"content_type": "video/mp4",
"file_type": "video",
"bytes": 235680,
"created_at": 1793836800,
"quota": {
"limit": 2000,
"used": 124,
"remaining": 1876,
"window_hours": 72,
"reset_at": 1794063600
}
}
{
"error": {
"message": "insufficient balance: uploading files requires a positive account balance, please top up",
"type": "insufficient_user_quota"
}
}
{
"error": {
"message": "video file exceeds maximum 52428800 bytes (50MB)",
"type": "invalid_request_error"
}
}
{
"error": {
"message": "upload limit reached: each account can upload at most 2000 files per 72 hours",
"type": "rate_limit_exceeded",
"code": "rate_limit_exceeded",
"param": ""
},
"quota": {
"limit": 2000,
"used": 2000,
"remaining": 0,
"window_hours": 72,
"reset_at": 1794063600
}
}
Manajemen Unggahan
Unggah Video
Unggah video MP4, MOV, atau WebM untuk mendapatkan URL publik bagi API pembuatan. Batas default: 50MB per file.
POST
/
v1
/
uploads
/
videos
curl --request POST \
--url https://api.apimart.ai/v1/uploads/videos \
--header 'Authorization: Bearer <token>' \
--form 'file=@/path/to/reference.mp4'
import requests
with open("reference.mp4", "rb") as file:
response = requests.post(
"https://api.apimart.ai/v1/uploads/videos",
headers={"Authorization": "Bearer <token>"},
files={"file": file}
)
response.raise_for_status()
result = response.json()
print(result["url"])
const input = document.querySelector('input[type="file"]');
const file = input?.files?.[0];
if (!file) throw new Error("Select a file first");
const formData = new FormData();
formData.append("file", file, file.name);
const response = await fetch("https://api.apimart.ai/v1/uploads/videos", {
method: "POST",
headers: { Authorization: "Bearer <token>" },
body: formData
});
const result = await response.json();
if (!response.ok) {
throw new Error(result.error?.message ?? `HTTP ${response.status}`);
}
console.log(result.url);
{
"url": "https://cdn.example/uploads/reference.mp4",
"filename": "reference.mp4",
"content_type": "video/mp4",
"file_type": "video",
"bytes": 235680,
"created_at": 1793836800,
"quota": {
"limit": 2000,
"used": 124,
"remaining": 1876,
"window_hours": 72,
"reset_at": 1794063600
}
}
{
"error": {
"message": "insufficient balance: uploading files requires a positive account balance, please top up",
"type": "insufficient_user_quota"
}
}
{
"error": {
"message": "video file exceeds maximum 52428800 bytes (50MB)",
"type": "invalid_request_error"
}
}
{
"error": {
"message": "upload limit reached: each account can upload at most 2000 files per 72 hours",
"type": "rate_limit_exceeded",
"code": "rate_limit_exceeded",
"param": ""
},
"quota": {
"limit": 2000,
"used": 2000,
"remaining": 0,
"window_hours": 72,
"reset_at": 1794063600
}
}
Unggah media referensi dan terima URL publik langsung saat berhasil; polling tidak diperlukan. Unggah gratis, tetapi saldo akun harus positif. Ketiga endpoint berbagi kuota per pengguna, secara default 2000 file dalam 72 jam.
Playground dokumentasi tidak mendukung unggah file. Gunakan contoh cURL, Python, atau JavaScript. Contoh JavaScript memerlukan
<input type="file"> dengan file yang telah dipilih.curl --request POST \
--url https://api.apimart.ai/v1/uploads/videos \
--header 'Authorization: Bearer <token>' \
--form 'file=@/path/to/reference.mp4'
import requests
with open("reference.mp4", "rb") as file:
response = requests.post(
"https://api.apimart.ai/v1/uploads/videos",
headers={"Authorization": "Bearer <token>"},
files={"file": file}
)
response.raise_for_status()
result = response.json()
print(result["url"])
const input = document.querySelector('input[type="file"]');
const file = input?.files?.[0];
if (!file) throw new Error("Select a file first");
const formData = new FormData();
formData.append("file", file, file.name);
const response = await fetch("https://api.apimart.ai/v1/uploads/videos", {
method: "POST",
headers: { Authorization: "Bearer <token>" },
body: formData
});
const result = await response.json();
if (!response.ok) {
throw new Error(result.error?.message ?? `HTTP ${response.status}`);
}
console.log(result.url);
{
"url": "https://cdn.example/uploads/reference.mp4",
"filename": "reference.mp4",
"content_type": "video/mp4",
"file_type": "video",
"bytes": 235680,
"created_at": 1793836800,
"quota": {
"limit": 2000,
"used": 124,
"remaining": 1876,
"window_hours": 72,
"reset_at": 1794063600
}
}
{
"error": {
"message": "insufficient balance: uploading files requires a positive account balance, please top up",
"type": "insufficient_user_quota"
}
}
{
"error": {
"message": "video file exceeds maximum 52428800 bytes (50MB)",
"type": "invalid_request_error"
}
}
{
"error": {
"message": "upload limit reached: each account can upload at most 2000 files per 72 hours",
"type": "rate_limit_exceeded",
"code": "rate_limit_exceeded",
"param": ""
},
"quota": {
"limit": 2000,
"used": 2000,
"remaining": 0,
"window_hours": 72,
"reset_at": 1794063600
}
}
Autentikasi
string
wajib
Gunakan APIMart API Key yang valid, aktif, dan belum kedaluwarsa sebagai
Bearer <token>. Akun tidak boleh diblokir dan saldonya harus positif. Kuota Key yang habis tidak mencegah unggah. Dapatkan Key di Pengelolaan API Key.Parameter permintaan
file
wajib
Kirim satu file beserta namanya melalui bidang
file dalam multipart/form-data. Jangan mengganti bagian file dengan JSON, string base64, atau URL. Bidang formulir lain diabaikan; jika beberapa bagian file dikirim, hanya yang pertama diproses.Format yang didukung: MP4 (.mp4), MOV (.mov), WebM (.webm)Batas ukuran file default: 50MB. Batas ukuran dapat dikonfigurasi. Ikuti konfigurasi aktif dan batas pada pesan kesalahan ukuran.--form, Python files, atau JavaScript FormData, biarkan klien membuat Content-Type beserta boundary. Jangan atur header ini secara manual.
Validasi file
Tipe dideteksi dari isi, bukan ekstensi atau MIME yang dinyatakan klien. Isi harus cocok dengan endpoint. Mengganti nama tidak mengonversi format; tipe yang salah menghasilkan HTTP400.
Struktur kontainer video diperiksa. Header palsu atau kontainer rusak ditolak. Hanya format di bawah yang didukung; mengganti nama AVI, MKV, atau lainnya tidak membuatnya valid.
| Format | Tipe MIME terdeteksi |
|---|---|
| MP4 (.mp4) | video/mp4 |
| MOV (.mov) | video/quicktime |
| WebM (.webm) | video/webm |
Respons berhasil
HTTP200 mengembalikan informasi file. url ada di tingkat teratas JSON, tanpa pembungkus data atau ID tugas pembuatan.
string
URL publik untuk parameter referensi yang sesuai pada API pembuatan. Setiap model tetap memiliki batas format, ukuran, jumlah, dan durasi sendiri. Unggah berhasil tidak menjamin kecocokan dengan model.
string
Nama file asli.
string
Tipe MIME yang dideteksi server dari isi file, bukan nilai yang dinyatakan klien.
string
Kategori file. Endpoint ini mengembalikan
video.integer
Ukuran file sebenarnya dalam byte.
integer
Waktu unggah sebagai timestamp Unix dalam detik.
object
Informasi kuota unggah opsional. Bidang pengguna dengan batas ada di bawah. Struktur dapat berbeda untuk akses tanpa batas atau statistik yang tidak tersedia.
| Bidang | Keterangan |
|---|---|
quota.limit | Maksimal unggah berhasil pengguna ini dalam jendela; dapat berbeda dari default 2000. |
quota.used | Jumlah yang dipakai dalam jendela, termasuk unggah berhasil ini. |
quota.remaining | Jumlah file yang saat ini masih dapat diunggah. |
quota.window_hours | Panjang jendela dalam jam; default 72. |
quota.reset_at | Waktu kelompok catatan tertua keluar dari jendela, dalam detik Unix. Sebagian slot tersedia kembali, bukan berarti semua kuota direset sekaligus. |
Kuota bersama dan batas permintaan
Gambar, video, dan audio berbagi kuota per pengguna. Beberapa Key milik pengguna yang sama tidak menambah kuota. Jendela bergeser setiap pergantian jam dan secara default menghitung unggah berhasil selama sekitar 71–72 jam terakhir. File tidak valid, terlalu besar, atau gagal disimpan tidak memakai kuota file. Respons dengan kuota terbatas biasa menyertakanX-Upload-Quota-Limit, X-Upload-Quota-Remaining, dan X-Upload-Quota-Reset, sesuai limit, remaining, dan reset_at. Reset memakai detik Unix.
Pengguna tanpa batas menerima quota: {"unlimited": true} tanpa ketiga header tersebut. Saat statistik sementara tidak tersedia, respons berhasil dapat menghilangkan quota. Jangan mengartikannya sebagai nol atau tanpa batas, atau mengunggah ulang hanya karena statistik tidak ada.
Kuota file habis menghasilkan HTTP 429, error.type: rate_limit_exceeded, quota dengan remaining: 0, dan Retry-After. Tunggu jumlah detik yang diberikan. Batas terpisah sebesar 1000 permintaan per Key per 60 detik memakai rate_limit_error.
Penanganan kesalahan
Kesalahan ada dalam objekerror di tingkat teratas JSON. Periksa status HTTP, error.type / error.code, dan error.message.
| HTTP | error.type | Penyebab dan tindakan |
|---|---|---|
| 400 | invalid_request_error | File tidak ada, bukan multipart, file kosong, tipe salah, format tidak didukung, atau isi rusak. Perbaiki file atau endpoint. |
| 401 / 403 | — | Key tidak valid atau dinonaktifkan, atau akun diblokir. Periksa autentikasi dan status akun. |
| 402 | insufficient_user_quota | Saldo tidak positif atau Key kedaluwarsa. Tambah saldo atau gunakan Key valid. Unggah gratis tetap memerlukan syarat akses ini. |
| 413 | invalid_request_error | File melebihi batas tipenya. Kompres atau perkecil file; ikuti batas saat ini pada pesan kesalahan. |
| 429 | rate_limit_exceeded | Kuota file bersama habis. Baca quota dan Retry-After, lalu tunggu slot tersedia. |
| 429 | rate_limit_error | Permintaan Key terlalu sering. Kurangi frekuensi dan beri jeda sebelum mencoba kembali. |
| 503 | server_error | Terlalu banyak unggah video/audio bersamaan atau penyimpanan sementara tidak tersedia. Coba lagi nanti. |
| 500 | server_error | Gagal menyimpan file. Coba lagi nanti. |