Como obter uma chave de API - Alibaba Cloud Model Studio: Central de Documentação do Alibaba Cloud

Crie uma chave de API

Importante

Execute este procedimento com uma conta Alibaba Cloud ou um usuário RAM que possua permissões de página de administrator ou API-Key.

China (Beijing), Singapore e outras regiões

Acesse o console do Alibaba Cloud Model Studio. No canto superior direito, selecione uma região, como China (Beijing), Singapore, Japan (Tokyo), China (Hong Kong), ou Germany (Frankfurt). Acesse a página API Key e clique em Create API Key.
Na caixa de diálogo, configure as opções a seguir e clique em OK:
- Workspace: Selecione o workspace padrão.
- Permission: Selecione All. Para controle granular, escolha Custom e configure os endereços IP e modelos acessíveis.
Como escolher as configurações de permissão para uma chave de API?
O Alibaba Cloud Model Studio oferece dois tipos de configuração de permissão. Escolha uma conforme seus requisitos de negócio:
- All: Concede à chave de API permissão para chamar todos os modelos e aplicações.
- Custom: Permite configurar uma lista de permissões de endereços IP e um escopo de modelos acessíveis.
  
  Por padrão, todo o tráfego IPv4 ( 0.0.0.0/0 ) é permitido. O suporte a IPv6 está disponível apenas na região China (Beijing).
  
  Adicione até 20 endereços IPv4 ou IPv6, ou blocos CIDR, à lista de permissões de endereços IP.
Após a criação, a chave de API completa aparece em uma caixa de diálogo. Copie-a ou baixe-a e salve-a imediatamente. Mantenha-a em sigilo. Qualquer pessoa com sua chave de API pode fazer solicitações de service em seu nome, o que pode gerar cobranças. Após fechar a caixa de diálogo, você não poderá visualizar ou copiar a chave de API em texto simples novamente. Se perder a chave, redefina-a ou crie uma nova.

Uma conta Alibaba Cloud visualiza as chaves de API em todos os workspaces. Um usuário RAM visualiza apenas as chaves de API nos workspaces dos quais participa.

Na página de gerenciamento de API key, clique em + Create API key no canto superior direito para criar outra chave. Para uma chave de API existente, use Disable, Edit ou Delete na coluna Actions.

Região US (Virginia)

Acesse o console do Alibaba Cloud Model Studio. No canto superior direito, alterne a região para US (Virginia). Na aba Dashboard, escolha API Key no painel de navegação à esquerda. Na página de gerenciamento de chaves de API, clique em Create API Key.
Na caixa de diálogo, preencha as informações a seguir e clique em OK:
- Workspace: Selecione o workspace padrão.
- Description: Insira uma descrição para identificar a finalidade da chave de API.
Após a criação, a chave de API completa aparece em uma caixa de diálogo. Copie-a imediatamente e armazene-a com segurança. Não é possível visualizar a chave de API completa novamente após fechar a caixa de diálogo.
Na lista de chaves de API, clique no ícone ao lado de uma chave de API para copiar a chave mascarada.

Uma conta Alibaba Cloud visualiza as chaves de API em todos os workspaces. Um usuário RAM visualiza apenas as chaves de API nos workspaces dos quais participa.

Clique no botão + Create API key no canto superior direito para criar uma nova chave de API.

Quando usar outras contas proprietárias ou workspaces

Se precisar de colaboração em equipe ou alocação de custos, considere o seguinte:

Workspace: Um workspace isola recursos e permissões para diferentes projetos ou equipes. Para controlar quais modelos um grupo de usuários pode chamar ou para alocar custos de chamadas de modelo, crie ou selecione um sub-workspace na lista.

Para mais informações, consulte Permissões de chave de API e Consultar faturas e gerencie custos.

Configure a chave de API como variável de ambiente

Defina sua chave de API como uma variável de ambiente. Essa prática evita codificar a chave diretamente no código-source e reduz o risco de exposição acidental.

Linux

Permanente

Para disponibilizar a chave de API em todas as novas sessões do usuário atual, defina-a como uma variável de ambiente permanente.

Execute o comando a seguir para anexar a definição da variável de ambiente ao arquivo ~/.bashrc.
```
# Replace YOUR_DASHSCOPE_API_KEY with your DashScope API key
echo "export DASHSCOPE_API_KEY='YOUR_DASHSCOPE_API_KEY'" >> ~/.bashrc
```
Como alternativa, edite manualmente o arquivo ~/.bashrc.
Modificação manual
Execute o comando a seguir para abrir o arquivo ~/.bashrc.
```
nano ~/.bashrc
```
Adicione o conteúdo a seguir ao arquivo de configuração.
```
# Replace YOUR_DASHSCOPE_API_KEY with your DashScope API key
export DASHSCOPE_API_KEY="YOUR_DASHSCOPE_API_KEY"
```
No editor nano, pressione Ctrl+X, depois Y e, em seguida, Enter para salvar e fechar o arquivo.
Execute o comando a seguir para aplicar as alterações.
```
source ~/.bashrc
```
Abra uma nova janela de terminal e execute o comando a seguir para verificar se a variável de ambiente foi definida.
```
echo $DASHSCOPE_API_KEY
```

Temporária

Para usar a variável de ambiente apenas na sessão atual, defina-a como temporária.

Execute o comando a seguir.

# Replace YOUR_DASHSCOPE_API_KEY with your DashScope API key
export DASHSCOPE_API_KEY="YOUR_DASHSCOPE_API_KEY"

Execute o comando a seguir para verificar se a variável de ambiente foi definida.
```
echo $DASHSCOPE_API_KEY
```

macOS

Permanente

Para disponibilizar a chave de API em todas as novas sessões do usuário atual, defina-a como uma variável de ambiente permanente.

Execute o comando a seguir no terminal para verificar o tipo de shell padrão.
```
echo $SHELL
```
Prossiga conforme o tipo de shell padrão.
Zsh
1. Execute o comando a seguir para anexar a definição da variável de ambiente ao arquivo ~/.zshrc.
  # Replace YOUR_DASHSCOPE_API_KEY with your DashScope API key echo "export DASHSCOPE_API_KEY='YOUR_DASHSCOPE_API_KEY'" >> ~/.zshrc
  Como alternativa, edite manualmente o arquivo ~/.zshrc.
  Modificação manual
  
  Execute o comando a seguir para abrir o arquivo de configuração do shell.
  
  nano ~/.zshrc
  
  Adicione o conteúdo a seguir ao arquivo de configuração.
  
  # Replace YOUR_DASHSCOPE_API_KEY with your DashScope API key export DASHSCOPE_API_KEY="YOUR_DASHSCOPE_API_KEY"
  
  No editor nano, pressione Ctrl+X, depois Y e, em seguida, Enter para salvar e fechar o arquivo.
2. Execute o comando a seguir para aplicar as alterações.
  source ~/.zshrc
3. Abra uma nova janela de terminal e execute o comando a seguir para verificar se a variável de ambiente foi definida.
  echo $DASHSCOPE_API_KEY
Bash
1. Execute o comando a seguir para anexar a definição da variável de ambiente ao arquivo ~/.bash_profile.
  # Replace YOUR_DASHSCOPE_API_KEY with your DashScope API key echo "export DASHSCOPE_API_KEY='YOUR_DASHSCOPE_API_KEY'" >> ~/.bash_profile
  Como alternativa, edite manualmente o arquivo ~/.bash_profile.
  Modificação manual
  
  Execute o comando a seguir para abrir o arquivo de configuração do shell.
  
  nano ~/.bash_profile
  
  Adicione o conteúdo a seguir ao arquivo de configuração.
  
  # Replace YOUR_DASHSCOPE_API_KEY with your DashScope API key export DASHSCOPE_API_KEY="YOUR_DASHSCOPE_API_KEY"
  
  No editor nano, pressione Ctrl+X, depois Y e, em seguida, Enter para salvar e fechar o arquivo.
2. Execute o comando a seguir para aplicar as alterações.
  source ~/.bash_profile
3. Abra uma nova janela de terminal e execute o comando a seguir para verificar se a variável de ambiente foi definida.
  echo $DASHSCOPE_API_KEY

Temporária

Para usar a variável de ambiente apenas na sessão atual, defina-a como temporária.

O comando a seguir aplica-se tanto ao Zsh quanto ao Bash.

Execute o comando a seguir.

# Replace YOUR_DASHSCOPE_API_KEY with your DashScope API key
export DASHSCOPE_API_KEY="YOUR_DASHSCOPE_API_KEY"

Execute o comando a seguir para verificar se a variável de ambiente foi definida.
```
echo $DASHSCOPE_API_KEY
```

Windows

No Windows, configure uma variável de ambiente usando Propriedades do Sistema, Prompt de Comando ou Windows PowerShell.

System Properties

Nota

As variáveis de ambiente configuradas desta forma são permanentes.
São necessárias permissões de administrador para modificar variáveis de ambiente do sistema.
Alterações nas variáveis de ambiente não afetam aplicações em execução, incluindo janelas do Prompt de Comando e IDEs. Reinicie essas aplicações ou abra uma nova sessão de linha de comando para aplicar as alterações.

Na área de trabalho do Windows, pressione Win+Q, pesquise por Edit the system environment variables na caixa de pesquisa e clique no resultado para abrir a janela System Properties.
Na janela System Properties, clique em Environment Variable e, na seção System variables, clique em Create. Em Variable Name, insira DASHSCOPE_API_KEY e, em Variable value, insira sua DashScope API Key.
Clique em OK nas três janelas abertas para salvar as alterações e fechá-las.

Abra uma nova janela do Prompt de Comando ou Windows PowerShell e execute o comando apropriado para verificar se a variável de ambiente foi definida.

No Prompt de Comando:

echo %DASHSCOPE_API_KEY%

Microsoft Windows [Version 10.0.19045.5371]
(c) Microsoft Corporation. All rights reserved.
C:\Windows\system32>echo %DASHSCOPE_API_KEY%
sk-ee16697?fe4
C:\Windows\system32>

No Windows PowerShell:

echo $env:DASHSCOPE_API_KEY

Windows PowerShell
Copyright (C) Microsoft Corporation. All rights reserved.
Try the new cross-platform PowerShell https://aka.ms/pscore6
PS C:\Windows\system32> echo $env:DASHSCOPE_API_KEY
sk-ee166797fe40xxx
PS C:\Windows\system32>

Command Prompt

Permanente

Para disponibilizar a variável de ambiente da chave de API em todas as novas sessões do usuário atual, siga estas etapas.

Execute o comando a seguir no Prompt de Comando.

REM Replace YOUR_DASHSCOPE_API_KEY with your DashScope API key
setx DASHSCOPE_API_KEY "YOUR_DASHSCOPE_API_KEY"

Abra uma nova janela do Prompt de Comando para que a alteração tenha efeito.
Na nova janela do Prompt de Comando, execute o comando a seguir para verificar se a variável de ambiente foi definida.
```
echo %DASHSCOPE_API_KEY%
```

Temporária

Para usar a variável de ambiente apenas na sessão atual, execute o comando a seguir no Prompt de Comando.

REM Replace YOUR_DASHSCOPE_API_KEY with your DashScope API key
set DASHSCOPE_API_KEY=YOUR_DASHSCOPE_API_KEY

Execute o comando a seguir na mesma sessão para verificar se a variável de ambiente foi definida.

echo %DASHSCOPE_API_KEY%

Windows PowerShell

Permanente

Para disponibilizar a variável de ambiente da chave de API em todas as novas sessões do usuário atual, siga estas etapas.

Execute o comando a seguir no Windows PowerShell.

# Replace YOUR_DASHSCOPE_API_KEY with your DashScope API key
[Environment]::SetEnvironmentVariable("DASHSCOPE_API_KEY", "YOUR_DASHSCOPE_API_KEY", [EnvironmentVariableTarget]::User)

Abra uma nova janela do Windows PowerShell para que a alteração tenha efeito.
Na nova janela do Windows PowerShell, execute o comando a seguir para verificar se a variável de ambiente foi definida.
```
echo $env:DASHSCOPE_API_KEY
```

Temporária

Para usar a variável de ambiente apenas na sessão atual, execute o comando a seguir no PowerShell.

# Replace YOUR_DASHSCOPE_API_KEY with your DashScope API key
$env:DASHSCOPE_API_KEY = "YOUR_DASHSCOPE_API_KEY"

Execute o comando a seguir na mesma sessão para verificar se a variável de ambiente foi definida.

echo $env:DASHSCOPE_API_KEY

Usar uma chave de API

Método 1: Chamar modelos a partir de ferramentas de terceiros

Guias de configuração para ferramentas comuns: Chatbox, Cline, Claude Code, Dify, OpenClaw, Postman e Qwen Code.

Método 2: Chamar modelos usando código

Ao chamar a API do Qwen pela primeira vez via código, recomendamos configurar a chave de API como variável de ambiente para evitar codificá-la diretamente no código, o que reduz o risco de vazamentos.

Nota

Ao chamar um modelo via código ou ferramenta de terceiros, além da chave de API, especifique um endpoint de service (o API Host mostrado na caixa de diálogo de criação bem-sucedida, correspondente ao base_url no SDK ou requisição HTTP). O Model Studio fornece interfaces de protocolo compatíveis com OpenAI e Anthropic. O base_url difere entre os dois protocolos e varia conforme a região. Consulte a documentação do protocolo utilizado:

Protocolo compatível com OpenAI: Compatível com OpenAI - Chat
Protocolo compatível com Anthropic: Mensagens compatíveis com Anthropic

Não exponha sua chave de API.

Atualização de segurança da chave de API

O Model Studio atualizou o mecanismo de geração e armazenamento de chaves de API de pagamento conforme o uso para maior segurança (exceto na região US (Virginia)). As chaves de API criadas antes da atualização, iniciadas com sk-, permanecem totalmente funcionais e não sofrem alterações. Todas as chaves de API criadas após a atualização começam com sk-ws.

A tabela a seguir descreve as principais diferenças entre as chaves de API criadas antes e depois da atualização.

Item de comparação	Chaves pré-atualização	Chaves pós-atualização
Formato da chave	Começa com `sk-` e tem cerca de 32 caracteres.	Começa com `sk-ws` e é mais longa que o formato anterior.
Visualização em texto simples	Copie a chave completa em texto simples do console a qualquer momento.	A chave em texto simples aparece apenas uma vez na criação. Não é possível visualizá-la novamente após o fechamento da caixa de diálogo. Se perdida, redefina ou crie uma nova chave.
Capacidade de chamada	Chama modelos normalmente; a funcionalidade permanece inalterada.	Chama modelos normalmente; a funcionalidade é idêntica à das chaves pré-atualização.
Ação recomendada	Crie uma nova chave para substituir a antiga e aumentar a segurança.	Copie e salve a chave imediatamente após a criação e armazene-a com segurança.

Gerencie chaves de API pela API

Além das operações no console, o Alibaba Cloud Model Studio fornece operações OpenAPI para criar, consultar, editar, excluir, ativar, desativar e redefinir chaves de API programaticamente. Assim, você integra o gerenciamento de chaves de API a fluxos de trabalho automatizados.

Nota

Chamar as operações a seguir exige autenticação por assinatura com o AccessKey da sua conta Alibaba Cloud (não a própria chave de API) e as permissões RAM correspondentes. Depure cada operação online no portal de desenvolvedores OpenAPI ou chame-a por meio de um SDK da Alibaba Cloud.

Operação	Descrição
CreateApiKey	Cria uma chave de API.
GetApiKey	Consulta as informações de uma chave de API específica.
ListApiKeys	Consulta a lista de chaves de API.
UpdateApiKey	Edita uma chave de API, como descrição e configuração de permissões.
DeleteApiKey	Exclui uma chave de API. Esta operação não pode ser desfeita.
EnableApiKey	Ativa uma chave de API (indisponível na região US (Virginia)).
DisableApiKey	Desativa uma chave de API. A chave é mantida e pode ser reativada a qualquer momento (indisponível na região US (Virginia)).
ResetApiKey	Redefine uma chave de API. Um novo valor de chave é gerado e a chave antiga torna-se inválida imediatamente (indisponível na região US (Virginia)).

Permissões da chave de API

O workspace determina integralmente as permissões de uma chave de API. Todas as chaves de API dentro do mesmo workspace possuem permissões idênticas. Não é necessário criar chaves de API diferentes para modelos distintos, como modelos de texto para texto, texto para imagem ou síntese de fala.

Chave de API no workspace padrão: Chama todos os modelos padrão e qualquer aplicação dentro do workspace padrão.
Chave de API em um sub-workspace: Chama modelos padrão autorizados para o sub-workspace e qualquer aplicação dentro desse sub-workspace.

Nota

Ao clicar em Create API Key ou em Edit para uma chave de API existente, alterne as Permissions para Custom e configure o seguinte:

As configurações a seguir não têm suporte na região US (Virginia).

Lista de permissões de endereços IP: Permite que apenas endereços IP na lista usem a chave de API para fazer chamadas (suporta IPv4, IPv6 e blocos CIDR).
Access Scope: Selecione os modelos ou aplicações específicos que esta chave de API pode acessar. A chave não chama recursos não selecionados.

Validade da chave de API

As chaves de API não expiram. Elas permanecem válidas até que sejam excluídas manualmente.

Para conceder acesso temporário a aplicações ou usuários de terceiros, ou para controlar rigorosamente operações de alto risco, como acesso ou exclusão de dados sensíveis, gere uma chave de API temporária (válida por 60 segundos). Isso evita a exposição de uma chave de API de longo prazo e reduz o risco de vazamentos.

Códigos de erro

Se uma chamada de modelo falhar e retornar uma mensagem de erro, consulte Códigos de erro para solução de problemas.

FAQ

P: Quantas chaves de API posso criar em uma única conta Alibaba Cloud?

R: Nas regiões Singapore, China (Beijing), China (Hong Kong), Japan (Tokyo) e Germany (Frankfurt), cada conta Alibaba Cloud pode criar até 50 chaves de API por região.

Na região US (Virginia), cada conta proprietária, incluindo a conta Alibaba Cloud, pode criar até 20 chaves de API.

P: As chaves de API criadas por um usuário RAM continuam válidas após a exclusão do usuário?

R: Não. Após desativar ou excluir um usuário RAM no console RAM, todas as chaves de API criadas por esse usuário tornam-se inválidas e não podem mais ser usadas para chamadas de modelo.

P: Usei o comando echo e confirmei que a variável de ambiente foi definida corretamente. Por que meu código ainda informa que a chave de API não foi encontrada?

R: Isso pode ocorrer pelos seguintes motivos:

Cenário 1: Definição de variável de ambiente temporária. Uma variável temporária é válida apenas na sessão atual do terminal e não afeta IDEs ou outras aplicações em execução. Consulte as instruções neste tópico para definir uma variável de ambiente permanente.
Cenário 2: A IDE, ferramenta de linha de comando ou aplicação não foi reiniciada.
- Reinicie sua IDE (como VS Code) ou terminal para carregar as novas variáveis de ambiente.
- Se definiu a variável de ambiente após a implantação de uma aplicação, reinicie o service da aplicação para recarregar as variáveis de ambiente.
Cenário 3: Variável ausente em arquivo de configuração de service. Se um gerenciador de services, como systemd ou supervisord, iniciar sua aplicação, talvez seja necessário adicionar a variável de ambiente ao arquivo de configuração do gerenciador.
Cenário 4: Uso do comando sudo**. Ao usar sudo python xx.py para executar o script, as variáveis de ambiente do usuário atual podem não ser herdadas. Isso ocorre porque o sudo não herda todas as variáveis de ambiente por padrão. Utilize o comando sudo -E python xx.py, onde o parâmetro -E garante a passagem das variáveis de ambiente. Se tiver permissão para executar o script, execute python xx.py diretamente.