Obtain an API key

Before you use models or applications in Alibaba Cloud Model Studio, you must obtain an API key for authentication.

Obtain an API key

1. Go to the Alibaba Cloud Model Studio API Key page and select a region in the upper-right corner. Each region has its own endpoint, API keys, and model list, and they cannot be used across regions. For the API key entry and endpoint of each region, see Regional access information.

2. To create an API key, click Create API Key, configure the following options in the dialog box, and then click OK (if you cannot create an API key, contact a super administrator or a workspace administrator):

   • Owner account: The Alibaba Cloud account (primary account) is selected by default (the account name is usually a string of digits). To create an API key with independent ownership and responsibilities for team members or applications, and to implement fine-grained model access control together with workspaces, you can select a RAM user (account format: username@<AccountAlias>.onaliyun.com).
   • Workspace: The default workspace is selected by default (for quantity limits and primary account quotas, see Validity and limits). For permission isolation, fine-grained model access control, or independent cost accounting, select a non-default workspace. For more information, see Workspace management.
   • Permissions: We recommend that you select All. For more granular control, you can select Custom to configure the accessible IP addresses and accessible model scope (for quantity limits, see Validity and limits).

3. After the key is created, copy (or download and save) the complete API key in the dialog box immediately. A new API key is displayed in full only once at creation. After you close the dialog box, the list shows only a masked value, and you cannot view or copy the full plaintext again. If you do not save it, you must reset or create a new API key.

To create or manage API keys programmatically (for example, CreateApiKey and ListApiKeys), call the ModelStudio OpenAPI. Use the AccessKey of an Alibaba Cloud account or a RAM user to make the call. RAM users must have the AliyunBailianFullAccess system policy or a custom policy that includes the required permissions, such as modelstudio:CreateApiKey. The RAM permissions for this path and the super administrator or workspace administrator role required for console-based creation are independent of each other.

Configure the API key as an environment variable

• Method 1: Configure it in athird-party tool

  If you call models in tools or platforms such as Chatbox, you may need to enter three pieces of information:

  • The API key obtained in this topic

  • Base URL:

    • China (Beijing): https://dashscope.aliyuncs.com/compatible-mode/v1
    • Other regions: see Base URL overview

  • The model name, such as qwen-plus, qwen-max, or deepseek-v4-pro.

  We also provide configuration guides for common tools: Dify, Chatbox, Cline, Claude Code, Postman.

• Method 2: Configure the API key as an environment variable, which then supports cURL and code calls
  ImportantDo not configure or use a long-term API key in client-side code (such as browsers or mobile apps) or untrusted environments. You can use a temporary API key (valid for up to 1800 seconds).

  The <YOUR_API_KEY> in the following examples must be replaced with your actual API key.

  Linux

  Add a permanent environment variable

  Append the environment variable setting to the ~/.bashrc file.

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

  Add a temporary environment variable

  export DASHSCOPE_API_KEY='<YOUR_API_KEY>'
  echo "当前会话百炼 API Key 配置为：${DASHSCOPE_API_KEY:0:10}*********"
  

  Service manager (systemd)

  The following operations apply to scenarios where the application is deployed as a background service.

  1. Create an environment file

  sudo sh -c "echo 'DASHSCOPE_API_KEY=<YOUR_API_KEY>' > /etc/your-app/env"
  sudo chmod 600 /etc/your-app/env # 限制只有root用户有访问权限
  

  2. Modify the systemd service file (such as /etc/systemd/system/your-app.service):

  [Service]
  # 加载密钥文件
  EnvironmentFile=/etc/your-app/env
  ExecStart=/usr/bin/python /opt/your-app/main.py
  

  3. Reload the service

  sudo systemctl daemon-reload
  sudo systemctl restart your-app
  

  macOS

  Add a permanent environment variable

  Append the environment variable setting to the ~/.bash_profile or ~/.zshrc file.

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

  Add a temporary environment variable

  export DASHSCOPE_API_KEY='<YOUR_API_KEY>'
  echo "当前会话百炼 API Key 配置为：${DASHSCOPE_API_KEY:0:10}*********"
  

  Windows

  In Windows, you can configure environment variables by using System Properties, CMD, or PowerShell.

  System Properties

  Notes on the System Properties method:

  • The environment variable takes effect permanently.
  • Modifying system environment variables requires administrator permissions.
  • After configuration, the change does not immediately affect command-line windows, IDEs, or other running applications that are already open. Restart these programs or open a new command line for the environment variable to take effect.

  1. On the Windows desktop, press Win+Q, search for Edit the system environment variables in the search box, and click to open the System Properties window.

  2. In the System Properties window, click Environment Variables. In the System variables section, click New. For Variable name, enter DASHSCOPE_API_KEY. For Variable value, enter your DashScope API key.

  3. Click OK in all three windows to close the System Properties configuration page and complete the environment variable configuration.

  4. Open a Command Prompt (CMD) or Windows PowerShell window and run the following command to check whether the environment variable takes effect.

     • CMD query command:

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

  • Windows PowerShell query command:

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

  CMD

  Add a permanent environment variable

  If you want the API key environment variable to take effect in all new sessions of the current user, follow these steps.

  1. Run the following command in CMD.

  setx DASHSCOPE_API_KEY "<YOUR_API_KEY>"
  

  2. Open a new CMD window.
  3. In the new CMD window, run the following command to check whether the environment variable takes effect.

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

  Add a temporary environment variable

  If you want to use the environment variable only in the current session, run the following command in CMD.

  set "DASHSCOPE_API_KEY=<YOUR_API_KEY>"
  

  You can run the following command in the current session to check whether the environment variable takes effect.

  echo 当前会话百炼 API Key 配置为：%DASHSCOPE_API_KEY:~0,10%*********
  

  PowerShell

  Add a permanent environment variable

  If you want the API key environment variable to take effect in all new sessions of the current user, follow these steps.

  1. Run the following command in PowerShell.

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

  2. Open a new PowerShell window.
  3. In the new PowerShell window, run the following command to check whether the environment variable takes effect.

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

  Add a temporary environment variable

  If you want to use the environment variable only in the current session, run the following command in 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)))*********"
  

Validity and limits

API keys have no expiration time. If you need an API key with a validity period, you can generate a temporary API key (valid for up to 1800 seconds).

The status of an API key changes with account operations. Both the Alibaba Cloud account and RAM users with API key permission for the workspace can delete API keys.

Operation	API key of the primary account	API key of the RAM account
Manually delete the API key	Supported (the Alibaba Cloud account has this permission by default; RAM users need the API key management permission for the workspace). Becomes invalid immediately after deletion and cannot be recovered.	Supported (the Alibaba Cloud account has this permission by default; RAM users need the API key management permission for the workspace). Becomes invalid immediately after deletion and cannot be recovered.
Remove the account from a workspace	—	The API key becomes invalid after the account is removed from the workspace, and becomes valid again after the account rejoins the workspace
Delete the account/role in theRAM console	—	API keys created before March 25, 2026: deleted with the RAM user and cannot be recovered. API keys created on or after March 25, 2026: not affected and remain valid.

Async tasks after an API key is deleted

After an API key is deleted, it can no longer be used and cannot be recovered. If async tasks associated with the API key have not started or have not finished running, the system will still run these tasks normally after the API key is deleted.

If you are sure that you do not want the associated async tasks to continue, manually terminate the related tasks to avoid incurring charges after the API key is deleted.

Quantity and permission limits

Summary of API key-related limits:

• Number of API keys: Up to 50 per account per region, not limited by workspace; a single primary account can have up to 20 workspaces (including the default workspace).
• Models selectable for custom permissions: Up to 30, limited to the models authorized for the workspace.
• IP address whitelist: Up to 20 addresses or CIDR blocks; IPv6 is supported only in the China (Beijing) region; separate multiple entries with commas.
• Temporary API key: Valid for up to 1800 seconds.

API calls

See the API references for text generation and more models.

For models supported by the OpenAI SDK, see OpenAI compatibility.

FAQ

Unable to create an API key?

API keys must be created by a super administrator or a workspace administrator.

How do I manage API key permissions?

The call permissions of an API key are entirely determined by its workspace. All API keys in the same workspace have identical permissions. You do not need to create different API keys for different models (such as text-to-text, text-to-image, or speech synthesis).

• API keys in the default workspace: Can call all standard models and the applications in the default workspace.
• API keys in a sub-workspace: Can call the standard models for which the sub-workspace has been granted model call authorization, as well as the applications in that workspace.

Calling afine-tuned model: After such a model is deployed in Alibaba Cloud Model Studio, it can only be called by the API key of the workspace it belongs to.

For more fine-grained control beyond workspaces, switch Permissions to Custom when creating or editing an API key and configure:

• IP address whitelist rules: All IPv4 addresses are allowed by default. For the complete rules, see Validity and limits.
• Accessible model scope: After the toggle is enabled, the API key can only call the selected models (limited to the models authorized for the workspace; for quantity limits, see Validity and limits).

The environment variable is set, but why does my code still report that the API key cannot be found?

The specific reasons are as follows:

• Scenario 1: No permanent environment variable is set. A temporary environment variable is valid only in the current terminal session and does not take effect for IDEs or other applications that are already running. Refer to the method in this topic for setting a permanent environment variable.

• Scenario 2: The IDE, command-line tool, or application was not restarted.

  • You usually need to restart your IDE (such as VS Code) or command-line tool so that it can load the latest environment variables.
  • If you set the environment variable after deploying the application, you may need to restart the application service so that the application can reload the environment variables.

• Scenario 3: You need to add the environment variable to a configuration file. If your application is started by a service manager (such as systemd or supervisord), you may need to add the environment variable to the service manager's configuration file.

• Scenario 4: Used thesudocommand. If you run the script with sudo python xx.py, the environment variables of the current user may be missed, because sudo does not inherit all environment variables by default. You can use the sudo -E python xx.py command, where the -E parameter ensures that the environment variables are passed. If you have permission to run the script, you can run python xx.py directly.

How many API keys can I create under a single primary account?

Each primary account can create up to 20 workspaces (including the default workspace); the number of API keys is 50 per account per region, not limited by workspace.