> ## Documentation Index > Fetch the complete documentation index at: https://docs.apimart.ai/llms.txt > Use this file to discover all available pages before exploring further. # Unggah Audio > Unggah audio MP3, WAV, atau M4A untuk mendapatkan URL publik bagi API pembuatan. Batas default: 15MB per file. > [!NOTE] > > 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. > [!NOTE] > > Playground dokumentasi tidak mendukung unggah file. Gunakan contoh cURL, Python, atau JavaScript. Contoh JavaScript memerlukan `` dengan file yang telah dipilih. ```bash cURL theme={null} curl --request POST \ --url https://api.apimart.ai/v1/uploads/audios \ --header 'Authorization: Bearer ' \ --form 'file=@/path/to/reference.mp3' ``` ```python Python theme={null} import requests with open("reference.mp3", "rb") as file: response = requests.post( "https://api.apimart.ai/v1/uploads/audios", headers={"Authorization": "Bearer "}, files={"file": file} ) response.raise_for_status() result = response.json() print(result["url"]) ``` ```javascript JavaScript theme={null} 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/audios", { method: "POST", headers: { Authorization: "Bearer " }, body: formData }); const result = await response.json(); if (!response.ok) { throw new Error(result.error?.message ?? `HTTP ${response.status}`); } console.log(result.url); ``` ```json 200 theme={null} { "url": "https://cdn.example/uploads/reference.mp3", "filename": "reference.mp3", "content_type": "audio/mpeg", "file_type": "audio", "bytes": 235680, "created_at": 1793836800, "quota": { "limit": 2000, "used": 124, "remaining": 1876, "window_hours": 72, "reset_at": 1794063600 } } ``` ```json 402 theme={null} { "error": { "message": "insufficient balance: uploading files requires a positive account balance, please top up", "type": "insufficient_user_quota" } } ``` ```json 413 theme={null} { "error": { "message": "audio file exceeds maximum 15728640 bytes (15MB)", "type": "invalid_request_error" } } ``` ```json 429 theme={null} { "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 **Authorization** `string` *required* Gunakan APIMart API Key yang valid, aktif, dan belum kedaluwarsa sebagai `Bearer `. Akun tidak boleh diblokir dan saldonya harus positif. Kuota Key yang habis tidak mencegah unggah. Dapatkan Key di [Pengelolaan API Key](https://apimart.ai/keys). ## Parameter permintaan **file** `file` *required* 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:** MP3 (.mp3), WAV (.wav), M4A (.m4a) **Batas ukuran file default:** 15MB. Batas ukuran dapat dikonfigurasi. Ikuti konfigurasi aktif dan batas pada pesan kesalahan ukuran. Dengan cURL `--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 HTTP `400`. Struktur kontainer atau frame audio diperiksa. Header palsu dan file rusak ditolak. OGG, FLAC, serta AAC sebagai aliran ADTS mentah tidak didukung. | Format | Tipe MIME terdeteksi | | - | - | | MP3 (.mp3) | `audio/mpeg` | | WAV (.wav) | `audio/wav` | | M4A (.m4a) | `audio/mp4` | ## Respons berhasil HTTP `200` mengembalikan informasi file. `url` ada di tingkat teratas JSON, tanpa pembungkus `data` atau ID tugas pembuatan. **url** `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. **filename** `string` Nama file asli. **content\_type** `string` Tipe MIME yang dideteksi server dari isi file, bukan nilai yang dinyatakan klien. **file\_type** `string` Kategori file. Endpoint ini mengembalikan `audio`. **bytes** `integer` Ukuran file sebenarnya dalam byte. **created\_at** `integer` Waktu unggah sebagai timestamp Unix dalam detik. **quota** `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 menyertakan `X-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 objek `error` 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. | ## Penggunaan URL dan penyimpanan file 72 jam adalah jendela kuota default, bukan jaminan masa penyimpanan file. Masa simpan mengikuti kebijakan penyimpanan. Simpan file asli dan segera gunakan URL untuk pembuatan; jangan anggap URL berlaku permanen. ## Endpoint unggah lainnya * [Unggah Gambar](https://docs.apimart.ai/id/api-reference/uploads/images.md) * [Unggah Video](https://docs.apimart.ai/id/api-reference/uploads/videos.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.