擷取與配置 API Key

​

第一步：擷取 API Key

1. 前往阿里雲百鍊的密鑰管理（國際版| 中國大陸版）頁面。
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.aliyuncs.com/compatible-mode/v1
    • 國際版：https://dashscope-intl.aliyuncs.com/compatible-mode/v1
  • 模型名稱，如 qwen-plus、qwen3-8b、deepseek-r1 等。
• 方式二：配置 API Key 到環境變數，後續支援 cURL 和代碼調用
  請勿在用戶端代碼（如瀏覽器、行動裝置 App）或不可信環境中配置或使用長期有效 API Key。可以使用臨時 API Key（最長 1800 秒）。

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

  • Linux系統
  • macOS系統
  • Windows系統

  • 添加永久性環境變數
  • 添加臨時性環境變數
  • 服務管理員 (systemd)

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

  Copy

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

  Copy

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

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

  1. 建立環境檔案

  Copy

  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）：

  Copy

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

  3. 重載服務

  Copy

  sudo systemctl daemon-reload
  sudo systemctl restart your-app
  

  • 添加永久性環境變數
  • 添加臨時性環境變數

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

  Copy

  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}*********"
  

  Copy

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

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

  • 系統屬性
  • CMD
  • PowerShell

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

  1. 在Windows系統案頭中按Win+Q鍵，在搜尋方塊中搜尋編輯系統內容變數，單擊開啟系統屬性介面。
  2. 在系統屬性視窗，單擊環境變數，然後在系統變數地區下單擊建立，變數名填入DASHSCOPE_API_KEY，變數值填入您的DashScope API Key。
  3. 依次單擊三個視窗的確定，關閉系統屬性配置頁面，完成環境變數配置。
  4. 開啟CMD（命令提示字元）視窗或Windows PowerShell視窗，執行如下命令檢查環境變數是否生效。
     • CMD查詢命令：

  Copy

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

  • Windows PowerShell查詢命令：

  Copy

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

  • 添加永久性環境變數
  • 添加臨時性環境變數

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

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

  Copy

  setx DASHSCOPE_API_KEY "<YOUR_API_KEY>"
  

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

  Copy

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

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

  Copy

  set "DASHSCOPE_API_KEY=<YOUR_API_KEY>"
  

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

  Copy

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

  • 添加永久性環境變數
  • 添加臨時性環境變數

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

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

  Copy

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

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

  Copy

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

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

  Copy

  $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。