Model multimodal seperti Qwen-VL memerlukan URL file sebagai input gambar, video, dan audio. Model Studio menyediakan ruang penyimpanan sementara gratis bagi pengguna yang tidak memiliki URL publik: unggah file dan dapatkan URL oss:// yang berlaku selama 48 jam .
dashscope-intl.aliyuncs.com dengan dashscope.aliyuncs.com pada URL permintaan, dan gunakan API key wilayah Beijing (API key untuk kedua wilayah berbeda; lihat API key).Cara kerja
- Unggah file dan tentukan model target. API akan mengembalikan URL
oss://. - Gunakan URL tersebut dalam pemanggilan model Anda. Anda harus menyelesaikan Langkah 2 untuk menggunakan URL sementara—melewatkannya akan menyebabkan error. Untuk panggilan HTTP, tambahkan header
X-DashScope-OssResourceResolve: enable. SDK DashScope menambahkan header ini secara otomatis.
Batasan
Kendala | Detail |
|---|---|
Pengikatan file-model | Tentukan nama model saat mengunggah. Gunakan model yang sama dalam panggilan berikutnya—file tidak dapat dibagikan lintas model. |
Batas Ukuran File | Ukuran file tidak boleh melebihi 1GB dan juga harus mematuhi batas spesifik model yang dipilih. |
Pengikatan file-akun | API key untuk unggah dan panggilan model harus berasal dari Akun Alibaba Cloud yang sama—file tidak dapat dibagikan lintas akun. |
Kedaluwarsa 48 jam | File dihapus secara otomatis setelah 48 jam. Selesaikan panggilan model dalam periode ini. |
Tidak ada manajemen pasca-unggah | File tidak dapat diinterogasi, dimodifikasi, atau diunduh—file hanya berfungsi sebagai parameter URL dalam panggilan model. |
Batas laju | API kredensial unggah dibatasi hingga 100 QPS per akun per model. Permintaan berlebih akan gagal. Ruang penyimpanan sementara tidak mendukung scale-out. |
Prasyarat
Sebelum memulai:
- API key yang dikonfigurasi sebagai variabel lingkungan
- Nama model yang akan menggunakan file tersebut (misalnya,
qwen3-vl-plus)
Langkah 1: Dapatkan URL sementara
Unggah file dan dapatkan URL sementaranya menggunakan salah satu metode berikut:
- Unggah dengan kode
- Unggah dengan CLI
- Python
- Java
- Python 3.9 atau lebih baru
- Instal dependensi:
Parameter | Deskripsi | Contoh |
|---|---|---|
| Model Studio API key | Dibaca dari variabel lingkungan |
| Model yang akan menggunakan file tersebut |
|
| Jalur ke file lokal |
|
Langkah 2: Panggil model dengan URL sementara
Setelah mengunggah file, gunakan URL oss:// dalam panggilan model Anda. Dua aturan berlaku:
- Konsistensi model: Gunakan model yang sama seperti yang ditentukan saat unggah.
- Konsistensi akun: Gunakan API key yang berasal dari Akun Alibaba Cloud yang sama.
HTTP
Saat memanggil API melalui HTTP (curl, Postman, dll.), tambahkan header ini:
oss:// dan permintaan akan gagal.
Contoh permintaan
Contoh ini memanggil qwen3-vl-plus untuk mendeskripsikan gambar yang diunggah.
Ganti oss://... dengan URL sementara Anda yang sebenarnya.
DashScope SDK
SDK DashScope menangani header X-DashScope-OssResourceResolve secara otomatis—berikan URL oss:// langsung sebagai parameter file.
SDK OpenAI tidak didukung. Tidak semua model mendukung panggilan SDK—lihat referensi API model tertentu untuk detailnya.
- Python
- Java
2.0.1 atau lebih baru.Contoh ini memanggil qwen3-vl-plus untuk mendeskripsikan gambar yang diunggah. Kode ini berlaku untuk model qwen-vl dan omni.
Ganti oss://... pada parameter gambar dengan URL sementara Anda yang sebenarnya.
Referensi API
Kode contoh dan CLI pada Langkah 1 membungkus tiga operasi API berikut secara internal. Gunakan referensi ini untuk mengimplementasikan alur unggah secara manual.
Dapatkan kredensial unggah file
Parameter permintaan
Lokasi | Bidang | Tipe | Wajib | Deskripsi | Contoh |
|---|---|---|---|---|---|
Header | Content-Type | _string_ | Ya | Jenis permintaan. |
|
Header | Authorization | _string_ | Ya | Model Studio API key. |
|
Params | action | _string_ | Ya | Jenis operasi. Atur ke |
|
Params | model | _string_ | Ya | Nama model target. |
|
Parameter respons
Bidang | Tipe | Deskripsi | Contoh |
|---|---|---|---|
request_id | _string_ | ID permintaan unik. |
|
data | _object_ | - | - |
data.policy | _string_ | Kredensial unggah. |
|
data.signature | _string_ | Tanda tangan kredensial. |
|
data.upload_dir | _string_ | Jalur direktori unggah. |
|
data.upload_host | _string_ | Host OSS untuk unggah. | |
data.expire_in_seconds | _string_ | Masa berlaku kredensial dalam detik. Dapatkan kredensial baru setelah kedaluwarsa. |
|
data.max_file_size_mb | _string_ | Ukuran maksimum file unggah dalam MB. Berbeda-beda tergantung model. |
|
data.capacity_limit_mb | _string_ | Kapasitas unggah harian per Akun Alibaba Cloud dalam MB. |
|
data.oss_access_key_id | _string_ | Kunci akses untuk unggah. |
|
data.x_oss_object_acl | _string_ | Izin akses file yang diunggah. |
|
data.x_oss_forbid_overwrite | _string_ | Apakah penimpaan file dengan nama yang sama diblokir. |
|
Contoh permintaan
Jika API key tidak dikonfigurasi sebagai variabel lingkungan, ganti$DASHSCOPE_API_KEYdengan API key Anda:--header "Authorization: Bearer sk-xxx".
Contoh respons
Unggah file ke ruang penyimpanan sementara
Ganti{data.upload_host}dengandata.upload_hostdari respons kredensial.
Parameter permintaan
Lokasi | Bidang | Tipe | Wajib | Deskripsi | Contoh |
|---|---|---|---|---|---|
Header | Content-Type | _string_ | Tidak | Kirim formulir sebagai |
|
form-data | OSSAccessKeyId | _text_ | Ya |
|
|
form-data | policy | _text_ | Ya |
|
|
form-data | Signature | _text_ | Ya |
|
|
form-data | key | _text_ | Ya |
|
|
form-data | x-oss-object-acl | _text_ | Ya |
|
|
form-data | x-oss-forbid-overwrite | _text_ | Ya |
|
|
form-data | success_action_status | _text_ | Tidak | Kode status HTTP yang dikembalikan saat sukses. Biasanya |
|
form-data | file | _file_ | Ya | File yang akan diunggah. Hanya satu file per permintaan. Bidang |
|
Contoh permintaan
Buat URL file
Gabungkan oss:// dengan key dari permintaan unggah. URL ini berlaku selama 48 jam.
Kode kesalahan
Jika panggilan API gagal, lihat Pesan kesalahan untuk troubleshooting umum.
Kode kesalahan berikut khusus untuk unggah file sementara:
Status HTTP | Kode kesalahan | Pesan kesalahan | Penyebab dan penyelesaian |
|---|---|---|---|
400 | invalid_parameter_error | InternalError.Algo.InvalidParameter: URL yang diberikan tampaknya tidak valid. Pastikan formatnya benar. | URL salah format. Verifikasi format URL. Jika menggunakan URL |
400 | InvalidParameter.DataInspection | Format media tidak didukung atau salah untuk inspeksi data. | Header permintaan tidak memiliki |
403 | AccessDenied | Invalid according to Policy: Policy expired. | Kredensial unggah telah kedaluwarsa. Panggil ulang API kredensial untuk mendapatkan yang baru. |
429 | Throttling.RateQuota | Batas laju permintaan terlampaui, silakan coba lagi nanti. | Laju permintaan melebihi 100 QPS. Kurangi frekuensi permintaan, atau migrasi ke OSS untuk beban kerja produksi. |
FAQ
Apa yang harus saya lakukan jika URL oss:// mengembalikan error?
Ikuti langkah-langkah berikut:
- Periksa header permintaan. Jika memanggil API melalui HTTP (curl, Postman, dll.), tambahkan
X-DashScope-OssResourceResolve: enableke header permintaan. Tanpa header ini, server tidak dapat menyelesaikan protokoloss://. SDK DashScope menambahkan header ini secara otomatis. - Periksa masa berlaku URL. URL
oss://kedaluwarsa 48 jam setelah diunggah. Jika sudah kedaluwarsa, unggah ulang file untuk mendapatkan URL baru.