Skip to main content
更多

上傳本地檔案擷取臨時URL

在調用多模態、映像、視頻或音頻模型時,通常需要傳入檔案的 URL。為此,阿里雲百鍊提供了 免費 臨時儲存空間,您可將本地檔案上傳至該空間並獲得 URL( 有效期間為 48 小時 )。

本文檔僅適用於華北2(北京)地區。如需使用模型,需使用華北2(北京)地區的API Key

使用限制

  • 檔案與模型繫結:檔案上傳時必須指定模型名稱,且該模型須與後續調用的模型一致,不同模型無法共用檔案。
  • 檔案大小限制:介面上傳檔案大小不得超過1GB,超出限制將導致上傳失敗。此外,不同模型對輸入檔案大小有不同限制,超出限制將導致模型調用失敗。
  • 檔案與主帳號綁定:檔案上傳與模型調用所使用的 API Key 必須屬於同一個阿里雲主帳號,且上傳的檔案僅限該主帳號及其對應模型使用,無法被其他主帳號或其他模型共用。
  • 檔案有效期間限制:檔案上傳後有效期間48小時,逾時後檔案將被自動清理,請確保在有效期間內完成模型調用。
  • 檔案使用限制:檔案一旦上傳,不可查詢、修改或下載,僅能通過URL參數在模型調用時使用
  • 檔案上傳限流:檔案上傳憑證介面的調用限流按照“阿里雲主帳號+模型”維度為100QPS超出限流將導致請求失敗
  • 臨時 URL 有效期間48小時,到期後無法使用,請勿用於生產環境。
  • 檔案上傳憑證介面限流為 100 QPS 且不支援擴容,請勿用於生產環境、高並發及壓測情境。
  • 生產環境建議使用阿里雲OSS 等穩定儲存,確保檔案長期可用並規避限流問題。

使用方式

  1. 擷取檔案 URL:請先通過步驟一上傳檔案(圖片、視頻或音頻),擷取以oss:// 為首碼的臨時 URL。
  2. 調用模型:請務必根據步驟二使用臨時 URL 進行調用。該步驟不能跳過,否則介面將報錯。

步驟一:擷取臨時URL

  • 方式一:通過代碼上傳檔案
  • 方式二:通過命令列工具上傳檔案
本文提供 Python 和 Java 範例程式碼,簡化上傳檔案操作。您只需指定模型和待上傳的檔案,即可擷取臨時URL。前提條件在調用前,您需要擷取API Key,再配置API Key到環境變數

範例程式碼

  • Python
  • Java
環境配置
  • 推薦使用Python 3.8及以上版本。
  • 請安裝必要的依賴包。
pip install -U requests
輸入參數
  • api_key:阿里雲百鍊API KEY。
  • model_name:指定檔案將要用於哪個模型,如qwen-vl-plus
  • file_path:待上傳的本地檔案路徑(圖片、視頻等)。
import os
import requests
from pathlib import Path
from datetime import datetime, timedelta

def get_upload_policy(api_key, model_name):
    """擷取檔案上傳憑證"""
    url = "https://dashscope.aliyuncs.com/api/v1/uploads"
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }
    params = {
        "action": "getPolicy",
        "model": model_name
    }

    response = requests.get(url, headers=headers, params=params)
    if response.status_code != 200:
        raise Exception(f"Failed to get upload policy: {response.text}")

    return response.json()['data']

def upload_file_to_oss(policy_data, file_path):
    """將檔案上傳到臨時儲存OSS"""
    file_name = Path(file_path).name
    key = f"{policy_data['upload_dir']}/{file_name}"

    with open(file_path, 'rb') as file:
        files = {
            'OSSAccessKeyId': (None, policy_data['oss_access_key_id']),
            'Signature': (None, policy_data['signature']),
            'policy': (None, policy_data['policy']),
            'x-oss-object-acl': (None, policy_data['x_oss_object_acl']),
            'x-oss-forbid-overwrite': (None, policy_data['x_oss_forbid_overwrite']),
            'key': (None, key),
            'success_action_status': (None, '200'),
            'file': (file_name, file)
        }

        response = requests.post(policy_data['upload_host'], files=files)
        if response.status_code != 200:
            raise Exception(f"Failed to upload file: {response.text}")

    return f"oss://{key}"

def upload_file_and_get_url(api_key, model_name, file_path):
    """上傳檔案並擷取URL"""
    # 1. 擷取上傳憑證,上傳憑證介面有限流,超出限流將導致請求失敗
    policy_data = get_upload_policy(api_key, model_name)
    # 2. 上傳檔案到OSS
    oss_url = upload_file_to_oss(policy_data, file_path)

    return oss_url

# 使用樣本
if __name__ == "__main__":
    # 從環境變數中擷取API Key 或者 在代碼中設定 api_key = "your_api_key"
    api_key = os.getenv("DASHSCOPE_API_KEY")
    if not api_key:
        raise Exception("請設定DASHSCOPE_API_KEY環境變數")

    # 設定model名稱
    model_name="qwen-vl-plus"

    # 待上傳的檔案路徑
    file_path = "/tmp/cat.png"  # 替換為實際檔案路徑

    try:
        public_url = upload_file_and_get_url(api_key, model_name, file_path)
        expire_time = datetime.now() + timedelta(hours=48)
        print(f"檔案上傳成功,有效期間為48小時,到期時間: {expire_time.strftime('%Y-%m-%d %H:%M:%S')}")
        print(f"臨時URL: {public_url}")
        print("注意:使用oss://形式的臨時URL時,必須在HTTP要求標頭(Header)中顯式添加參數:X-DashScope-OssResourceResolve: enable,具體請參考:https://www.alibabacloud.com/help/zh/model-studio/get-temporary-file-url#http-call")

    except Exception as e:
        print(f"Error: {str(e)}")
輸出樣本
檔案上傳成功,有效期間為48小時,到期時間: 2024-07-18 17:36:15
臨時URL: oss://dashscope-instant/xxx/2024-07-18/xxx/cat.png
注意:使用oss://形式的臨時URL時,必須在HTTP要求標頭(Header)中顯式添加參數:X-DashScope-OssResourceResolve: enable,具體請參考:https://www.alibabacloud.com/help/zh/model-studio/get-temporary-file-url#http-call
擷取臨時 URL 後,調用時必須在 HTTP 要求頭(Header)中顯式添加參數:X-DashScope-OssResourceResolve: enable,具體請參見通過HTTP調用

步驟二:使用臨時URL調用模型

使用限制

  • 檔案格式:臨時URL須通過上述方式產生,且以 oss://為首碼的URL字串。
  • 檔案未到期:檔案URL仍在上傳後的48小時有效期間內。
  • 模型一致:模型調用所使用的模型必須與檔案上傳時指定的模型完全一致。
  • 帳號一致:模型調用的API KEY必須與檔案上傳時使用的API KEY同屬一個阿里雲主帳號。

方式一:通過HTTP調用

通過curl、Postman或任何其他HTTP用戶端直接調用API,則必須遵循以下規則
  • 使用臨時URL,必須在請求的Header中添加參數:X-DashScope-OssResourceResolve: enable
  • 若缺失此Header,系統將無法解析oss://連結,請求將失敗,報錯資訊請參考錯誤碼
  • 請求樣本
  • 響應樣本
  • 上傳的本地圖片樣本
本樣本為調用 qwen-vl-plus 模型識別圖片內容。
請將 oss://...替換為真實的臨時 URL,否則請求將失敗。
curl -X POST https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-H 'X-DashScope-OssResourceResolve: enable' \
-d '{
  "model": "qwen-vl-plus",
  "messages": [{
      "role": "user",
      "content":
      [{"type": "text","text": "這是什麼"},
       {"type": "image_url","image_url": {"url": "oss://dashscope-instant/xxx/2024-07-18/xxxx/cat.png"}}]
    }]
}'

方式二:通過DashScope SDK調用

您也可以使用阿里雲百鍊提供的 Python 或 Java SDK。
  • 直接傳入 URL:調用模型 SDK 時,直接將以oss://為首碼的URL字串作為檔案參數傳入。
  • 無需關心 Header:SDK 會自動添加必需的要求標頭,無需額外操作。
注意:並非所有模型都支援 SDK 調用,請以模型 API 文檔為準。
不支援 OpenAI SDK。
  • Python
  • Java
前提條件安裝DashScope Python SDK,且DashScope Python SDK版本號碼 >=1.24.0範例程式碼本樣本為調用 qwen-vl-plus 模型識別圖片內容。此程式碼範例僅適用於 qwen-vl 和 omni 系列模型。
  • 請求樣本
  • 響應樣本
請將 image 參數中的 oss://...替換為真實的臨時 URL,否則請求將失敗。
import os
import dashscope

messages = [
    {
        "role": "system",
        "content": [{"text": "You are a helpful assistant."}]
    },
    {
        "role": "user",
        "content": [
            {"image": "oss://dashscope-instant/xxx/2024-07-18/xxxx/cat.png"},
            {"text": "這是什麼"}]
    }]

# 若沒有配置環境變數,請用百鍊API Key將下行替換為:api_key="sk-xxx"
api_key = os.getenv('DASHSCOPE_API_KEY')

response = dashscope.MultiModalConversation.call(
    api_key=api_key,
    model='qwen-vl-plus',
    messages=messages
)

print(response)

附介面說明

在上述擷取臨時URL的兩種方式中,代碼調用和命令列工具已整合以下三個步驟,簡化檔案上傳操作。以下是各步驟的介面說明。

步驟1:擷取檔案上傳憑證

前提條件
您需要已擷取API Key配置API Key到環境變數
請求介面
GET https://dashscope.aliyuncs.com/api/v1/uploads
檔案上傳憑證介面限流為 100 QPS(按“阿里雲主帳號+模型”維度),且臨時儲存不可擴容。生產環境或高並發情境請使用阿里雲OSS等儲存服務。
入參描述

傳參方式

欄位

類型

必選

描述

樣本值

Header

Content-Type

string

請求類型:application/json 。

application/json

Authorization

string

阿里雲百鍊API Key,例如:Bearer sk-xxx。

Bearer sk-xxx

Params

action

string

操作類型,當前情境為getPolicy

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地址。

https://dashscope-file-xxx.oss-cn-beijing.aliyuncs.com

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表示私人。

private

data.x_oss_forbid_overwrite

string

檔案同名時是否可以覆蓋,true表示不可覆蓋。

true

請求樣本
curl --location 'https://dashscope.aliyuncs.com/api/v1/uploads?action=getPolicy&model=qwen-vl-plus' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json'
若未配置阿里雲百鍊API Key到環境變數,請將$DASHSCOPE_API_KEY替換為實際API Key,例如:--header "Authorization: Bearer sk-xxx"

響應樣本

{
    "request_id": "52f4383a-c67d-9f8c-xxxxxx",
    "data": {
        "policy": "eyJl...1ZSJ=",
        "signature": "YOUR_SIGNATURE",
        "upload_dir": "dashscope-instant/xxx/2024-07-18/xxx",
        "upload_host": "https://dashscope-file-xxx.oss-cn-beijing.aliyuncs.com",
        "expire_in_seconds": 300,
        "max_file_size_mb": 100,
        "capacity_limit_mb": 999999999,
        "oss_access_key_id": "LTA...",
        "x_oss_object_acl": "private",
        "x_oss_forbid_overwrite": "true"
    }
}

步驟2:上傳檔案至臨時儲存空間

前提條件

  • 已擷取檔案上傳憑證。
  • 確保檔案上傳憑證在有效期間內,若憑證到期,請重新調用步驟1的介面擷取新的憑證。
    查看檔案上傳憑證有效期間:步驟1的輸出參數data.expire_in_seconds為憑證有效期間,單位為秒。

請求介面

POST {data.upload_host}
請將{data.upload_host}替換為步驟1的輸出參數data.upload_host對應的值。

入參描述

傳參方式欄位類型必選描述樣本值
HeaderContent-Typestring提交表單必須為multipart/form-data在提交表單時,Content-Type會以multipart/form-data;boundary=xxxxxx的形式展示。
boundary 是自動產生的隨機字串,無需手動指定。若使用 SDK 拼接表單,SDK 也會自動產生該隨機值。
multipart/form-data; boundary=9431149156168
form-dataOSSAccessKeyIdtext檔案上傳憑證介面的輸出參數 data.oss_access_key_id 的值。LTAm5xxx
policytext檔案上傳憑證介面的輸出參數 data.policy 的值。g5K...d40=
Signaturetext檔案上傳憑證介面的輸出參數 data.signature 的值。YOUR_SIGNATURE
keytext檔案上傳憑證介面的輸出參數 data.upload_dir 的值拼接上/ 檔案名稱例如,upload_dirdashscope-instant/xxx/2024-07-18/xxx,需要上傳的檔案名稱為 cat.png,拼接後的完整路徑為:dashscope-instant/xxx/2024-07-18/xxx/cat.png
x-oss-object-acltext檔案上傳憑證介面的輸出參數 data.x_oss_object_acl 的值。private
x-oss-forbid-overwritetext檔案上傳憑證介面的輸出參數中data.x_oss_forbid_overwrite 的值。true
success_action_statustext通常取值為 200,上傳完成後介面返回 HTTP code 200,表示操作成功。200
filetext檔案或常值內容。
  • 一次只支援上傳一個檔案。
  • file必須為最後一個表單域,除file以外的其他表單域並無順序要求。
例如,待上傳檔案cat.png在Linux系統中的儲存路徑為/tmp,則此處應為file=@"/tmp/cat.png"

出參描述

調用成功時,本介面無任何參數輸出。

請求樣本

curl --location 'https://dashscope-file-xxx.oss-cn-beijing.aliyuncs.com' \
--form 'OSSAccessKeyId="LTAm5xxx"' \
--form 'Signature="Sm/tv7DcZuTZftFVvt5yOoSETsc="' \
--form 'policy="eyJleHBpcmF0aW9 ... ... ... dHJ1ZSJ9XX0="' \
--form 'x-oss-object-acl="private"' \
--form 'x-oss-forbid-overwrite="true"' \
--form 'key="dashscope-instant/xxx/2024-07-18/xxx/cat.png"' \
--form 'success_action_status="200"' \
--form 'file=@"/tmp/cat.png"'

步驟3:組建檔案URL

檔案URL拼接邏輯:oss:// + key (步驟2的入參key)。該URL有效期間為 48 小時。
oss://dashscope-instant/xxx/2024-07-18/xxxx/cat.png

錯誤碼

如果介面調用失敗並返回報錯資訊,請參見錯誤碼進行解決。 本文的API還有特定狀態代碼,具體如下所示。
HTTP狀態代碼介面錯誤碼(code)介面錯誤資訊(message)含義說明
400invalid_parameter_errorInternalError.Algo.InvalidParameter: The provided URL does not appear to be valid. Ensure it is correctly formatted.無效URL,請檢查URL是否填寫正確。
若使用臨時檔案URL,需確保請求的 Header 中添加了參數 X-DashScope-OssResourceResolve: enable
400InvalidParameter.DataInspectionThe media format is not supported or incorrect for the data inspection.可能的原因有:
  • 請求Header 缺少必要參數,請設定 X-DashScope-OssResourceResolve: enable
  • 上傳的圖片格式不符合模型要求,更多資訊請參見錯誤碼
403AccessDeniedInvalid according to Policy: Policy expired.檔案上傳憑證已經到期。請重新調用檔案上傳憑證介面產生新憑證。
429Throttling.RateQuotaRequests rate limit exceeded, please try again later.調用頻次觸發限流。檔案上傳憑證介面限流為 100 QPS(按阿里雲主帳號 + 模型維度)。觸發限流後,建議降低請求頻率,或遷移至 OSS 等自有儲存服務以規避限制。

常見問題

Q:使用oss://首碼的 URL 調用時報錯,該如何處理?

A:請按以下步驟排查:
  1. 檢查要求標頭(Header)
    若您通過 HTTP(如 Postman、curl)直接調用,必須在Header中添加參數X-DashScope-OssResourceResolve: enable。未添加該參數會導致服務端無法識別 OSS 內部協議。關於要求標頭配置,請參見通過HTTP調用
  2. 檢查 URL 有效性
    oss:// 連結為臨時 URL,請確保該連結是48小時內產生的。如果連結已到期,請重新上傳檔案擷取新的 URL。

Q:檔案上傳與模型調用使用的API KEY可以不一樣嗎?

A:檔案儲存體和存取權限基於阿里雲主帳號管理,API Key 僅為主帳號的訪問憑證。 因此,同一阿里雲主帳號下的不同 API Key 可正常使用,不同主帳號的 API Key因帳號隔離,模型調用無法跨帳號讀取檔案。 請確保檔案上傳與模型調用使用的 API Key 屬於同一阿里雲主帳號。
上傳本地檔案擷取臨時URL - Alibaba Cloud Model Studio