在調用多模態、映像、視頻或音頻模型時,通常需要傳入檔案的 URL。為此,阿里雲百鍊提供了 免費 臨時儲存空間,您可將本地檔案上傳至該空間並獲得 URL( 有效期間為 48 小時 )。
使用限制
- 檔案與模型繫結:檔案上傳時必須指定模型名稱,且該模型須與後續調用的模型一致,不同模型無法共用檔案。
- 檔案大小限制:介面上傳檔案大小不得超過1GB,超出限制將導致上傳失敗。此外,不同模型對輸入檔案大小有不同限制,超出限制將導致模型調用失敗。
- 檔案與主帳號綁定:檔案上傳與模型調用所使用的 API Key 必須屬於同一個阿里雲主帳號,且上傳的檔案僅限該主帳號及其對應模型使用,無法被其他主帳號或其他模型共用。
- 檔案有效期間限制:檔案上傳後有效期間48小時,逾時後檔案將被自動清理,請確保在有效期間內完成模型調用。
- 檔案使用限制:檔案一旦上傳,不可查詢、修改或下載,僅能通過URL參數在模型調用時使用。
- 檔案上傳限流:檔案上傳憑證介面的調用限流按照“阿里雲主帳號+模型”維度為100QPS,超出限流將導致請求失敗。
使用方式
步驟一:擷取臨時URL
- 方式一:通過代碼上傳檔案
- 方式二:通過命令列工具上傳檔案
範例程式碼
- Python
- Java
- 推薦使用Python 3.8及以上版本。
- 請安裝必要的依賴包。
- api_key:阿里雲百鍊API KEY。
- model_name:指定檔案將要用於哪個模型,如
qwen-vl-plus。 - file_path:待上傳的本地檔案路徑(圖片、視頻等)。
步驟二:使用臨時URL調用模型
使用限制
- 檔案格式:臨時URL須通過上述方式產生,且以
oss://為首碼的URL字串。 - 檔案未到期:檔案URL仍在上傳後的48小時有效期間內。
- 模型一致:模型調用所使用的模型必須與檔案上傳時指定的模型完全一致。
- 帳號一致:模型調用的API KEY必須與檔案上傳時使用的API KEY同屬一個阿里雲主帳號。
方式一:通過HTTP調用
通過curl、Postman或任何其他HTTP用戶端直接調用API,則必須遵循以下規則:
- 請求樣本
- 響應樣本
- 上傳的本地圖片樣本
oss://...替換為真實的臨時 URL,否則請求將失敗。方式二:通過DashScope SDK調用
您也可以使用阿里雲百鍊提供的 Python 或 Java SDK。
- 直接傳入 URL:調用模型 SDK 時,直接將以
oss://為首碼的URL字串作為檔案參數傳入。 - 無需關心 Header:SDK 會自動添加必需的要求標頭,無需額外操作。
不支援 OpenAI SDK。
- Python
- Java
1.24.0。範例程式碼本樣本為調用 qwen-vl-plus 模型識別圖片內容。此程式碼範例僅適用於 qwen-vl 和 omni 系列模型。- 請求樣本
- 響應樣本
oss://...替換為真實的臨時 URL,否則請求將失敗。附介面說明
在上述擷取臨時URL的兩種方式中,代碼調用和命令列工具已整合以下三個步驟,簡化檔案上傳操作。以下是各步驟的介面說明。
步驟1:擷取檔案上傳憑證
前提條件
您需要已擷取API Key並配置API Key到環境變數。請求介面
入參描述
傳參方式 | 欄位 | 類型 | 必選 | 描述 | 樣本值 |
|---|---|---|---|---|---|
Header | Content-Type | string | 是 | 請求類型:application/json 。 | application/json |
Authorization | string | 是 | 阿里雲百鍊API Key,例如:Bearer sk-xxx。 | Bearer sk-xxx | |
Params | action | string | 是 | 操作類型,當前情境為 | getPolicy |
model | string | 是 | 需要調用的模型名稱。 | qwen-vl-plus |
出參描述
欄位 | 類型 | 描述 | 樣本值 |
|---|---|---|---|
request_id | string | 本次請求的系統唯一碼。 | 7574ee8f-...-11c33ab46e51 |
data | object | - | - |
data.policy | string | 上傳憑證。 | eyJl...1ZSJ9XX0= |
data.signature | string | 上傳憑證的簽名。 | g5K...d40= |
data.upload_dir | string | 上傳檔案的目錄。 | dashscope-instant/xxx/2024-07-18/xxxx |
data.upload_host | string | 上傳的host地址。 | |
data.expire_in_seconds | string | 憑證有效期間(單位:秒)。 到期後,重新調用本介面擷取新的憑證。 | 300 |
data.max_file_size_mb | string | 本次允許上傳的最大檔案的大小(單位:MB)。 該值與需要訪問的模型相關。 | 100 |
data.capacity_limit_mb | string | 同一個主帳號每天上傳容量限制(單位:MB)。 | 999999999 |
data.oss_access_key_id | string | 用於上傳的access key。 | LTAxxx |
data.x_oss_object_acl | string | 上傳檔案的存取權限, | private |
data.x_oss_forbid_overwrite | string | 檔案同名時是否可以覆蓋, | true |
請求樣本
$DASHSCOPE_API_KEY替換為實際API Key,例如:--header "Authorization: Bearer sk-xxx"。響應樣本
步驟2:上傳檔案至臨時儲存空間
前提條件
- 已擷取檔案上傳憑證。
-
確保檔案上傳憑證在有效期間內,若憑證到期,請重新調用步驟1的介面擷取新的憑證。
查看檔案上傳憑證有效期間:步驟1的輸出參數
data.expire_in_seconds為憑證有效期間,單位為秒。
請求介面
data.upload_host對應的值。入參描述
| 傳參方式 | 欄位 | 類型 | 必選 | 描述 | 樣本值 |
|---|---|---|---|---|---|
| Header | Content-Type | string | 否 | 提交表單必須為multipart/form-data。在提交表單時,Content-Type會以multipart/form-data;boundary=xxxxxx的形式展示。boundary 是自動產生的隨機字串,無需手動指定。若使用 SDK 拼接表單,SDK 也會自動產生該隨機值。 | multipart/form-data; boundary=9431149156168 |
| form-data | OSSAccessKeyId | text | 是 | 檔案上傳憑證介面的輸出參數 data.oss_access_key_id 的值。 | LTAm5xxx |
| policy | text | 是 | 檔案上傳憑證介面的輸出參數 data.policy 的值。 | g5K...d40= | |
| Signature | text | 是 | 檔案上傳憑證介面的輸出參數 data.signature 的值。 | YOUR_SIGNATURE | |
| key | text | 是 | 檔案上傳憑證介面的輸出參數 data.upload_dir 的值拼接上/ 檔案名稱。 | 例如,upload_dir 為 dashscope-instant/xxx/2024-07-18/xxx,需要上傳的檔案名稱為 cat.png,拼接後的完整路徑為:dashscope-instant/xxx/2024-07-18/xxx/cat.png | |
| x-oss-object-acl | text | 是 | 檔案上傳憑證介面的輸出參數 data.x_oss_object_acl 的值。 | private | |
| x-oss-forbid-overwrite | text | 是 | 檔案上傳憑證介面的輸出參數中data.x_oss_forbid_overwrite 的值。 | true | |
| success_action_status | text | 否 | 通常取值為 200,上傳完成後介面返回 HTTP code 200,表示操作成功。 | 200 | |
| file | text | 是 | 檔案或常值內容。
| 例如,待上傳檔案cat.png在Linux系統中的儲存路徑為/tmp,則此處應為file=@"/tmp/cat.png"。 |
出參描述
調用成功時,本介面無任何參數輸出。
請求樣本
步驟3:組建檔案URL
檔案URL拼接邏輯:oss:// + key (步驟2的入參key)。該URL有效期間為 48 小時。
錯誤碼
如果介面調用失敗並返回報錯資訊,請參見錯誤碼進行解決。
本文的API還有特定狀態代碼,具體如下所示。
| HTTP狀態代碼 | 介面錯誤碼(code) | 介面錯誤資訊(message) | 含義說明 |
|---|---|---|---|
| 400 | invalid_parameter_error | InternalError.Algo.InvalidParameter: The provided URL does not appear to be valid. Ensure it is correctly formatted. | 無效URL,請檢查URL是否填寫正確。
若使用臨時檔案URL,需確保請求的 Header 中添加了參數 |
| 400 | InvalidParameter.DataInspection | The media format is not supported or incorrect for the data inspection. | 可能的原因有:
|
| 403 | AccessDenied | Invalid according to Policy: Policy expired. | 檔案上傳憑證已經到期。請重新調用檔案上傳憑證介面產生新憑證。 |
| 429 | Throttling.RateQuota | Requests rate limit exceeded, please try again later. | 調用頻次觸發限流。檔案上傳憑證介面限流為 100 QPS(按阿里雲主帳號 + 模型維度)。觸發限流後,建議降低請求頻率,或遷移至 OSS 等自有儲存服務以規避限制。 |
常見問題
Q:使用oss://首碼的 URL 調用時報錯,該如何處理?
A:請按以下步驟排查:
- 檢查要求標頭(Header):
若您通過 HTTP(如 Postman、curl)直接調用,必須在Header中添加參數X-DashScope-OssResourceResolve: enable。未添加該參數會導致服務端無法識別 OSS 內部協議。關於要求標頭配置,請參見通過HTTP調用。 - 檢查 URL 有效性:
oss://連結為臨時 URL,請確保該連結是48小時內產生的。如果連結已到期,請重新上傳檔案擷取新的 URL。