Alibaba Cloud Model Studio：擷取與配置 API Key

在控制台擷取或建立 API Key 後，您將使用它來安全地調用百鍊的模型服務。

第一步：擷取 API Key

1. 前往阿里雲百鍊密鑰管理頁面，在右上角選擇地區。

   每個地區有獨立的接入網域名稱、API Key 和模型列表，不能跨地區混用。各地區的密鑰管理入口和接入網域名稱，請參見各地區接入資訊。

2. 若已有可用 API Key，直接在列表中複製即可。若需建立，請遵循以下步驟：

   1. 在API Key 頁簽單擊建立 API Key。若無法建立，請聯絡您的組織或 IT 管理員。

   2. 在建立 API Key彈窗中，選擇 API Key 的歸屬帳號及歸屬業務空間，並單擊確定。

      • 歸屬帳號：選擇阿里雲帳號（主帳號）即可，帳號名通常為一串數字。

        如需為團隊成員或應用建立權責獨立的 API Key，並結合歸屬業務空間進行精細化的模型存取控制，歸屬帳號應選擇RAM 使用者。

        RAM 使用者的帳號格式為username@<AccountAlias>.onaliyun.com。

      • 歸屬業務空間：選擇“預設業務空間”，此空間下的 Key 可調用所有標準模型。

        單個業務空間最多支援建立 20 個 API Key。

        如需以下功能，請選擇非預設的業務空間，相關資訊請參考業務空間管理：

        • 對不同專案（業務空間）進行許可權隔離
        • 精細化的模型存取控制
        • 進行獨立的成本會計

      • 許可權：建議選擇全部，若有更精細的許可權控制需求，可以選擇自訂來控制可訪問 IP 和 可訪問模型。

        IP 白名單預設設定：IPv4（0.0.0.0/0）全部放通；IPv6 僅華北2（北京）地區支援，美國（維吉尼亞）地區僅支援 IPv4。最多支援 20 個地址或網段，批量輸入請用英文逗號隔開。

   3. 點擊新建立的 API Key 旁的表徵圖複製 API Key。

第二步：配置 API Key

• 方式一：在第三方工具中進行配置

  如果在 Chatbox 等工具或平台中調用模型，您可能需要輸入三個資訊：

  • 本文擷取的 API Key

  • Base URL：

    • 新加坡：https://dashscope-intl.aliyuncs.com/compatible-mode/v1
    • 其他地區：請參見Base URL 總覽

  • 模型名稱，如 qwen-plus、qwen3-8b、deepseek-r1 等。

• 方式二：配置 API Key 到環境變數，後續支援 cURL 和代碼調用
  重要請勿在用戶端代碼（如瀏覽器、行動裝置 App）或不可信環境中配置或使用長期有效 API Key。可以使用臨時 API Key（最長 1800 秒）。

  請將<YOUR_API_KEY> 部分替換為真實的 API Key。

  Linux系統

  添加永久性環境變數

  將環境變數設定追加到~/.bashrc檔案中。

  echo "export DASHSCOPE_API_KEY='<YOUR_API_KEY>'" >> ~/.bashrc
  source ~/.bashrc
  echo "百鍊 API Key 永久配置為：${DASHSCOPE_API_KEY:0:10}*********"
  

  添加臨時性環境變數

  export DASHSCOPE_API_KEY='<YOUR_API_KEY>'
  echo "當前會話百鍊 API Key 配置為：${DASHSCOPE_API_KEY:0:10}*********"
  

  服務管理員 (systemd)

  以下操作適用於將應用作為後台服務部署的情境。

  1. 建立環境檔案

  sudo sh -c "echo 'DASHSCOPE_API_KEY=<YOUR_API_KEY>' > /etc/your-app/env"
  sudo chmod 600 /etc/your-app/env # 限制只有root使用者有存取權限
  

  2. 修改 systemd 服務檔案（如 /etc/systemd/system/your-app.service）：

  [Service]
  # 載入密鑰檔案
  EnvironmentFile=/etc/your-app/env
  ExecStart=/usr/bin/python /opt/your-app/main.py
  

  3. 重載服務

  sudo systemctl daemon-reload
  sudo systemctl restart your-app
  

  macOS系統

  添加永久性環境變數

  將環境變數設定追加到~/.bash_profile或~/.zshrc檔案中。

  VAR_VALUE="<YOUR_API_KEY>"; \
  echo "export DASHSCOPE_API_KEY='$VAR_VALUE'" >> ~/.zshrc 2>/dev/null
  echo "export DASHSCOPE_API_KEY='$VAR_VALUE'" >> ~/.bash_profile 2>/dev/null
  source ~/."${SHELL##*/}rc" 2>/dev/null
  echo "百鍊 API Key 永久配置為：${DASHSCOPE_API_KEY:0:10}*********"
  

  添加臨時性環境變數

  export DASHSCOPE_API_KEY='<YOUR_API_KEY>'
  echo "當前會話百鍊 API Key 配置為：${DASHSCOPE_API_KEY:0:10}*********"
  

  Windows系統

  在Windows系統中，您可以通過系統屬性、CMD或PowerShell配置環境變數。

  系統屬性

  說明

  • 此方式配置的環境變數永久生效。
  • 修改系統內容變數需具備管理員權限。
  • 配置環境變數後不會立即影響已經開啟的命令視窗、IDE或其他正在啟動並執行應用程式。您需要重新啟動這些程式或者開啟新的命令列使環境變數生效。

  1. 在Windows系統案頭中按Win+Q鍵，在搜尋方塊中搜尋編輯系統內容變數，單擊開啟系統屬性介面。

  2. 在系統屬性視窗，單擊環境變數，然後在系統變數地區下單擊建立，變數名填入DASHSCOPE_API_KEY，變數值填入您的DashScope API Key。

  3. 依次單擊三個視窗的確定，關閉系統屬性配置頁面，完成環境變數配置。

  4. 開啟CMD（命令提示字元）視窗或Windows PowerShell視窗，執行如下命令檢查環境變數是否生效。

     • CMD查詢命令：

  echo 百鍊 API Key 永久配置為：%DASHSCOPE_API_KEY:~0,10%*********
  

  • Windows PowerShell查詢命令：

  Write-Host "百鍊 API Key 永久配置為：$($env:DASHSCOPE_API_KEY.Substring(0, [Math]::Min(10, $env:DASHSCOPE_API_KEY.Length)))*********"
  

  CMD

  添加永久性環境變數

  如果您希望API Key環境變數在目前使用者的所有新會話中生效，可以按如下操作。

  1. 在CMD中運行以下命令。

  setx DASHSCOPE_API_KEY "<YOUR_API_KEY>"
  

  2. 開啟一個新的CMD視窗。
  3. 在新的CMD視窗運行以下命令，檢查環境變數是否生效。

  echo 百鍊 API Key 永久配置為：%DASHSCOPE_API_KEY:~0,10%*********
  

  添加臨時性環境變數

  如果您僅希望在當前會話中使用該環境變數，可以在CMD中運行以下命令。

  set "DASHSCOPE_API_KEY=<YOUR_API_KEY>"
  

  您可以在當前會話運行以下命令檢查環境變數是否生效。

  echo 當前會話百鍊 API Key 配置為：%DASHSCOPE_API_KEY:~0,10%*********
  

  PowerShell

  添加永久性環境變數

  如果您希望API Key環境變數在目前使用者的所有新會話中生效，可以按如下操作。

  1. 在PowerShell中運行以下命令。

  [Environment]::SetEnvironmentVariable("DASHSCOPE_API_KEY", "<YOUR_API_KEY>", [EnvironmentVariableTarget]::User)
  

  2. 開啟一個新的PowerShell視窗。
  3. 在新的PowerShell視窗運行以下命令，檢查環境變數是否生效。

  Write-Host "百鍊 API Key 永久配置為：$($env:DASHSCOPE_API_KEY.Substring(0, [Math]::Min(10, $env:DASHSCOPE_API_KEY.Length)))*********"
  

  添加臨時性環境變數

  如果您僅希望在當前會話中使用該環境變數，可以在PowerShell中運行以下命令。

  $env:DASHSCOPE_API_KEY = "<YOUR_API_KEY>"
  Write-Host "當前會話百鍊 API Key 配置為：$($env:DASHSCOPE_API_KEY.Substring(0, [Math]::Min(10, $env:DASHSCOPE_API_KEY.Length)))*********"
  

API Key 時效性說明

API Key 沒有失效時間限制，若需要有時效性的 API Key，可產生臨時 API Key（有效期間最多1800秒）。

API Key 的狀態隨帳號操作而變化：

觸發操作	主帳號的 API Key	RAM 帳號的 API Key
主動刪除 API Key	不支援 失效，不可恢複	不支援 失效，不可恢複
將帳號移出業務空間	—	不支援 失效 重新加入業務空間後 API Key 恢複生效
在RAM 控制台刪除帳號/角色	—	不支援 失效，不可恢複

API 呼叫

請訪問文本產生以及更多模型的 API 參考。

OpenAI SDK 支援的模型，請參考OpenAI 相容。

常見問題

無法建立 API Key？

API Key 的建立需使用超級管理員或業務空間管理員操作。

如何管理 API Key 的許可權？

API Key 的調用許可權完全由其歸屬業務空間決定。同一空間內的 API Key 許可權相同，無需為不同模型（如文生文、文生圖、語音合成）建立不同的 API Key。

• 預設業務空間下的 API Key：可調用所有標準模型，以及預設業務空間內的應用。
• 子業務空間下的 API Key：可調用該子業務空間已獲得模型調用授權的標準模型，以及該業務空間內的應用。

如需在業務空間之外做更細粒度的控制，可在建立或編輯 API Key 時將許可權切換為自訂，配置：

• IP 訪問白名單：僅允許清單內的 IP 使用該 API Key 發起調用。支援 IPv4 與網段，預設 IPv4（0.0.0.0/0）全部放通；IPv6 僅華北2（北京）地區支援，美國（維吉尼亞）地區僅支援 IPv4。最多支援 20 個地址或網段，批量輸入請用英文逗號隔開。
• 訪問模型範圍：開關開啟後，該 API Key 僅能調用已勾選的模型，可選模型限於該業務空間已授權的模型。

環境變數已設定，為何代碼仍提示找不到 API Key？

具體原因如下：

• 情況一：沒有設定永久性環境變數。臨時環境變數只在當前終端會話中有效，對於已經啟動的 IDE 或其他應用程式並不會生效。請參考本文中設定永久性環境變數的方法。

• 情況二：沒有重啟IDE、命令列工具或應用。

  • 通常需要重啟 IDE（如 VS Code）或命令列工具，使其能夠載入最新的環境變數。
  • 如果在部署應用後設定了環境變數，可能需要重啟應用服務，讓應用能夠重新載入環境變數。

• 情況三：需要在設定檔添加環境變數。如果您的應用是通過服務管理員（如 systemd、supervisord）啟動的，可能需要在服務管理員的設定檔中添加環境變數。

• 情況四：用了sudo命令。如果使用sudo python xx.py運行指令碼，可能會遺漏目前使用者環境變數，因為sudo預設不繼承所有環境變數。您可採用sudo -E python xx.py命令，其中的-E 參數確保環境變數被傳遞。如有許可權執行該指令碼，可以直接執行 python xx.py。

單個主帳號下最多能建立多少個API Key？

每個主帳號下最多可建立10個業務空間（包括預設業務空間），每個業務空間下最多可建立20個API Key。