擷取API Key

重要

需使用主帳號，或具備管理員或API-Key頁面許可權的子帳號操作。

華北2（北京）、新加坡等地區

前往阿里雲百鍊控制台首頁，在頁面右上方選擇华北2（北京）、 新加坡、日本（東京）、中国香港、德国（法兰克福）地區，進入API Key頁面，單擊创建API Key。
在彈窗中配置以下資訊，並單擊确定：
- 归属业务空间：建議選擇預設業務空間。
- 描述（可選，最多200字元）：輸入描述資訊，方便後續識別該 API Key 的用途。
- 許可權：建議選擇全部，若有更精細的許可權控制需求，可以選擇自定义來控制可訪問 IP 和可訪問模型。
如何選擇 API Key 的許可權配置？
阿里雲百鍊提供兩種類型的許可權配置，請根據實際需求進行選擇：
- 全部：授予該 API Key 調用所有模型與應用的許可權。
- 自定义：可配置訪問 IP 白名單和可訪問模型範圍。
  
  IP 白名單預設設定：IPv4 （0.0.0.0/0）和 IPv6 （僅北京地區支援）全部放通。
  
  IP 白名單支援設定最多 20 個 IPv4、IPv6 的地址或網段。
建立成功後，彈窗會顯示完整的 API Key 和 API Host（服務端點地址）。請立即複製或下載儲存，注意妥善保管，任何擷取到該密鑰的人都能以您的身份發起服務要求併產生費用。關閉彈窗後將無法再次查看或複製明文 API Key。如果丟失，請重設或建立新的密鑰。

主帳號可查看所有業務空間下的 API Key；子帳號只能查看已加入業務空間中的 API Key。

美國（維吉尼亞）地區

前往阿里雲百鍊控制台首頁，在頁面右上方切換到美国（弗吉尼亚）地區，進入API Key管理頁面，單擊创建API Key。
在彈窗中配置以下資訊，並單擊确定：
- 归属业务空间：建議選擇預設業務空間。
- 歸屬帳號：選擇該 API Key 歸屬的帳號。
- 描述（可選，最多200字元）：輸入描述資訊，方便後續識別該 API Key 的用途。
建立成功後，彈窗會顯示完整的 API Key。請立即複製並妥善儲存，關閉彈窗後將無法再次查看完整的 API Key。
在API Key列表中，點擊API Key旁的表徵圖可複製脫敏後的API Key。

主帳號可查看所有業務空間下的 API Key；子帳號只能查看已加入業務空間中的 API Key。

API Key 管理操作

在 API Key 列表中，您可以對已有 API Key 執行以下操作：

編輯：修改 API Key 的描述和許可權配置。
刪除：永久刪除該 API Key，刪除後不可恢複。
禁用（美國（維吉尼亞）地區除外）：暫停該 API Key 的使用，不影響密鑰儲存，可隨時重新啟用。
重設（美國（維吉尼亞）地區除外）：產生新的密鑰值，舊密鑰立即失效。

何時選擇其他歸屬帳號或業務空間？

如果您有團隊協作或成本分攤需求，可以瞭解以下概念：

歸屬業務空間：用於隔離不同專案或團隊的資源和許可權。若需管控某類使用者可調用的模型，或對模型調用的費用進行分賬，請建立/挑選清單中的子業務空間。

詳情請參見API Key 許可權以及賬單查詢與成本管理。

配置API Key到環境變數

建議您把API Key配置到環境變數，從而避免在代碼裡顯式地配置API Key，降低泄漏風險。

Linux系統

添加永久性環境變數

如果您希望API Key環境變數在目前使用者的所有新會話中生效，可以添加永久性環境變數。

執行以下命令來將環境變數設定追加到~/.bashrc 檔案中。
```
# 用您的阿里雲百鍊API Key代替YOUR_DASHSCOPE_API_KEY
echo "export DASHSCOPE_API_KEY='YOUR_DASHSCOPE_API_KEY'" >> ~/.bashrc
```
也可以手動修改~/.bashrc 檔案。
手動修改
執行以下命令，開啟~/.bashrc 檔案。
```
nano ~/.bashrc
```
在設定檔中添加以下內容。
```
# 用您的阿里雲百鍊API Key代替YOUR_DASHSCOPE_API_KEY
export DASHSCOPE_API_KEY="YOUR_DASHSCOPE_API_KEY"
```
在nano編輯器中，按Ctrl + X，接著按Y，再按Enter以儲存並關閉檔案。
執行以下命令，使變更生效。
```
source ~/.bashrc
```
重新開啟一個終端視窗，運行以下命令檢查環境變數是否生效。
```
echo $DASHSCOPE_API_KEY
```

添加臨時性環境變數

如果您僅希望在當前會話中使用該環境變數，可以添加臨時性環境變數。

執行以下命令。

# 用您的阿里雲百鍊API Key代替YOUR_DASHSCOPE_API_KEY
export DASHSCOPE_API_KEY="YOUR_DASHSCOPE_API_KEY"

執行以下命令，驗證該環境變數是否生效。
```
echo $DASHSCOPE_API_KEY
```

macOS系統

添加永久性環境變數

如果您希望API Key環境變數在目前使用者的所有新會話中生效，可以添加永久性環境變數。

在終端中執行以下命令，查看預設Shell類型。
```
echo $SHELL
```
根據預設Shell類型進行操作。
Zsh
1. 執行以下命令來將環境變數設定追加到 ~/.zshrc 檔案中。
```
# 用您的阿里雲百鍊API Key代替YOUR_DASHSCOPE_API_KEY
echo "export DASHSCOPE_API_KEY='YOUR_DASHSCOPE_API_KEY'" >> ~/.zshrc
```
  也可以手動修改~/.zshrc 檔案。
  手動修改
  
  執行以下命令，開啟Shell設定檔。
  nano ~/.zshrc
  
  在設定檔中添加以下內容。
  # 用您的阿里雲百鍊API Key代替YOUR_DASHSCOPE_API_KEY export DASHSCOPE_API_KEY="YOUR_DASHSCOPE_API_KEY"
  
  在nano編輯器中，按Ctrl + X，接著按Y，再按Enter以儲存並關閉檔案。
2. 執行以下命令，使變更生效。
```
source ~/.zshrc
```
3. 重新開啟一個終端視窗，運行以下命令檢查環境變數是否生效。
```
echo $DASHSCOPE_API_KEY
```
Bash
1. 執行以下命令來將環境變數設定追加到 ~/.bash_profile 檔案中。
```
# 用您的阿里雲百鍊API Key代替YOUR_DASHSCOPE_API_KEY
echo "export DASHSCOPE_API_KEY='YOUR_DASHSCOPE_API_KEY'" >> ~/.bash_profile
```
  也可以手動修改~/.bash_profile 檔案。
  手動修改
  
  執行以下命令，開啟Shell設定檔。
  nano ~/.bash_profile
  
  在設定檔中添加以下內容。
  # 用您的阿里雲百鍊API Key代替YOUR_DASHSCOPE_API_KEY export DASHSCOPE_API_KEY="YOUR_DASHSCOPE_API_KEY"
  
  在nano編輯器中，按Ctrl + X，接著按Y，再按Enter以儲存並關閉檔案。
2. 執行以下命令，使變更生效。
```
source ~/.bash_profile
```
3. 重新開啟一個終端視窗，運行以下命令檢查環境變數是否生效。
```
echo $DASHSCOPE_API_KEY
```

添加臨時性環境變數

如果您僅希望在當前會話中使用該環境變數，可以添加臨時性環境變數。

以下命令適用於 Zsh 和 Bash。

執行以下命令。

# 用您的阿里雲百鍊API Key代替YOUR_DASHSCOPE_API_KEY
export DASHSCOPE_API_KEY="YOUR_DASHSCOPE_API_KEY"

執行以下命令，驗證該環境變數是否生效。
```
echo $DASHSCOPE_API_KEY
```

Windows系統

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

系統屬性

說明

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

在Windows系統案頭中按Win+Q鍵，在搜尋方塊中搜尋編輯系統內容變數，單擊開啟系統屬性介面。
在系統屬性視窗，單擊环境变量，然後在系統變數地區下單擊新建，变量名填入DASHSCOPE_API_KEY，變數值填入您的DashScope API Key。
依次單擊三個視窗的确定，關閉系統屬性配置頁面，完成環境變數配置。

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

CMD查詢命令：

echo %DASHSCOPE_API_KEY%

Microsoft Windows [版本 10.0.19045.5371]
(c) Microsoft Corporation。著作權所有，並保留一切權利。
C:\Windows\system32>echo %DASHSCOPE_API_KEY%
sk-ee16697?fe4
C:\Windows\system32>

Windows PowerShell查詢命令：

echo $env:DASHSCOPE_API_KEY

Windows PowerShell
著作權 (C) Microsoft Corporation。著作權所有，並保留一切權利。
嘗試新的跨平台 PowerShell https://aka.ms/pscore6
PS C:\Windows\system32> echo $env:DASHSCOPE_API_KEY
sk-ee166797fe40xxx
PS C:\Windows\system32>

CMD

添加永久性環境變數

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

在CMD中運行以下命令。

# 用您的阿里雲百鍊API Key代替YOUR_DASHSCOPE_API_KEY
setx DASHSCOPE_API_KEY "YOUR_DASHSCOPE_API_KEY"

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

添加臨時性環境變數

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

REM 用您的阿里雲百鍊API Key代替YOUR_DASHSCOPE_API_KEY
set DASHSCOPE_API_KEY=YOUR_DASHSCOPE_API_KEY

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

echo %DASHSCOPE_API_KEY%

PowerShell

添加永久性環境變數

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

在PowerShell中運行以下命令。

# 用您的阿里雲百鍊API Key代替YOUR_DASHSCOPE_API_KEY
[Environment]::SetEnvironmentVariable("DASHSCOPE_API_KEY", "YOUR_DASHSCOPE_API_KEY", [EnvironmentVariableTarget]::User)

開啟一個新的PowerShell視窗。
在新的PowerShell視窗運行以下命令，檢查環境變數是否生效。
```
echo $env:DASHSCOPE_API_KEY
```

添加臨時性環境變數

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

# 用您的阿里雲百鍊API Key代替YOUR_DASHSCOPE_API_KEY
$env:DASHSCOPE_API_KEY = "YOUR_DASHSCOPE_API_KEY"

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

echo $env:DASHSCOPE_API_KEY

使用API Key

方式一：在第三方工具中調用模型

常用工具配置：Chatbox、Cline、Claude Code、Dify、OpenClaw、Postman、Qwen Code。
方式二：通過代碼調用模型

通過代碼首次調用千問API，建議配置API Key到環境變數，以避免寫入程式碼在代碼中導致泄露風險。

請勿以任何方式公開API Key，避免因未經授權的使用導致安全風險或資金損失。

API Key 安全升級說明

百鍊已對隨用隨付 API Key 產生和儲存機制進行安全升級（美國（維吉尼亞）地區除外）。升級前已建立的sk-開頭的 API Key 可繼續正常使用，不受影響。升級後新建立的 API Key 統一以sk-ws開頭。

下表列出了升級前後 API Key 的主要差異。

對比項	升級前建立的 API Key	升級後建立的 API Key
Key 格式	以 `sk-` 開頭，長度較短（約 32 位）	以 `sk-ws` 開頭，長度較長
明文查看	可在控制台隨時複製完整明文	僅在建立時展示一次明文，關閉彈窗後無法再次查看。如果丟失，請進行重設或重新建立
調用能力	可正常調用模型，功能不受影響	可正常調用模型，與升級前功能完全一致
建議操作	建議建立新密鑰替換舊密鑰，以獲得更完善的安全保障	建立後請立即複製儲存，妥善保管

API Key許可權說明

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

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

說明

您可以在创建API Key 或點擊已有 API Key 操作列的编辑時，將权限切換為自定义，即可配置：

僅美國（維吉尼亞）地區不支援以下配置

IP 訪問白名單：僅允許清單內的 IP 使用該 API Key 發起調用（支援 IPv4、IPv6 與網段）。
访问权限范围：為該API Key 勾選可訪問的模型或應用；未勾選的資源無法通過此API Key 調用。

API Key時效性說明

建立的API Key沒有失效日期，手動刪除後即失效。

若需為第三方應用或使用者提供臨時存取權限，或需嚴格控制敏感性資料訪問、刪除等高風險操作，可產生臨時API Key（有效期間60秒），避免暴露長期有效API Key，降低泄露風險。

錯誤碼

如果模型調用失敗並返回報錯資訊，請參見錯誤碼進行解決。

常見問題

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

A：對於新加坡、華北2（北京）、中國香港、日本（東京）和德國（法蘭克福）地區，每個主帳號在每個地區最多可建立50個API Key。

對於美國（維吉尼亞）地區，每個歸屬帳號（包括主帳號）最多可建立20個API Key。

Q：RAM使用者被刪除後，其建立的API Key是否依然可用？

A：在RAM控制台中禁用或刪除RAM使用者後，其建立的所有API Key均將失效，無法再用於模型調用。

Q：用echo命令確認環境變數設定成功了，為什麼運行代碼還是提示找不到API Key？

A：具體原因如下：

情況一：沒有設定永久性環境變數。臨時環境變數只在當前終端會話有效，對於已經啟動的 IDE 或其他應用程式並不會生效。請參考本文中設定永久性環境變數的方法。
情況二：沒有重啟IDE、命令列工具或應用。
- 通常需要重啟IDE（如VS Code）或命令列工具，使其能夠載入最新的環境變數。
- 如果在部署應用後設定了環境變數，可能需要重啟應用服務，讓應用能夠重新載入環境變數。
情況三：需要在設定檔添加環境變數。如果您的應用是通過服務管理員（如systemd、supervisord）啟動的，可能需要在服務管理員的設定檔中添加環境變數。
情況四：用了sudo命令。如果使用sudo python xx.py運行指令碼，可能會遺漏目前使用者環境變數，因為sudo預設不繼承所有環境變數。您可採用sudo -E python xx.py命令，其中的-E 參數確保環境變數被傳遞。如有許可權執行該指令碼，可以直接執行 python xx.py。