Skip to main content

Obtener una clave de API

Antes de utilizar modelos o aplicaciones en Alibaba Cloud Model Studio, debe obtener una clave de API para la autenticación.

Este tema describe la clave de API de pago por uso para Model Studio. Si está utilizando un Token Plan o Coding Plan, use la clave de API dedicada correspondiente (comienza con sk-sp-). Para obtener más información, consulte Clave de API de Token Plan y Clave de API de Coding Plan.

Creación de una clave API

Este procedimiento debe ser realizado por una cuenta de Alibaba Cloud o un usuario RAM con permisos de página de administrator o API-Key .
  • China (Beijing), Singapore y otras regiones
  • Región EE. UU. (Virginia)
  1. Vaya a la página de API Key de Alibaba Cloud Model Studio, seleccione una región en la esquina superior derecha y luego haga clic en Create API Key. Cada región tiene su propio endpoint, claves de API y lista de modelos. No se pueden usar entre regiones. Para la página de claves de API y el endpoint de cada región, consulte Información de acceso regional.
  2. En el cuadro de diálogo, configure los siguientes ajustes y luego haga clic en OK.
    • Workspace: Le recomendamos que seleccione el espacio de trabajo predeterminado.
    • Descripción (opcional, hasta 200 caracteres): Introduzca una descripción para ayudarle a identificar el propósito de la clave de API.
    • Permisos: Le recomendamos seleccionar All. Para un control más granular, seleccione Custom para configurar las direcciones IP y los modelos accesibles. Model Studio ofrece dos tipos: Todos otorga permiso para llamar a cualquier modelo o aplicación; Personalizado le permite configurar una lista blanca de direcciones IP y un alcance de modelos accesibles. De forma predeterminada, se permite todo el tráfico IPv4 (0.0.0.0/0); la compatibilidad con IPv6 está disponible únicamente en la región China (Beijing). Puede agregar hasta 20 direcciones IPv4 o IPv6 o bloques CIDR a la lista blanca de direcciones IP. Cuando el interruptor de Alcance de acceso está habilitado, puede seleccionar los modelos que la clave de API tiene permitido llamar de la lista de modelos (por ejemplo, Qwen3.7-Plus y Qwen3.7-Max). Después de la configuración, haga clic en OK.
  3. Después de crear la clave, la clave de API completa y el API Host (dirección del endpoint de servicio) se muestran en un cuadro de diálogo. Debe copiarlos o descargarlos y guardarlos inmediatamente. Manténgalos confidenciales. Cualquier persona que tenga su clave de API puede realizar solicitudes de servicio en su nombre, lo que podría generar cargos. Después de cerrar el cuadro de diálogo, no podrá volver a ver ni copiar la clave de API en texto plano. Si pierde la clave, restablézcala o cree una nueva. Una cuenta de Alibaba Cloud puede ver las claves de API en todos los espacios de trabajo. Un usuario de RAM solo puede ver las claves de API en los espacios de trabajo a los que se ha unido.

Operaciones de gestión de claves de API

En la lista de claves API, puede realizar las siguientes operaciones en las claves API existentes:
  • Editar: Modifica la descripción y la configuración de permisos de la clave API.
  • Eliminar: Elimina permanentemente la clave API. Esta operación no se puede deshacer.
  • Deshabilitar (no compatible en la región EE. UU. (Virginia)): Suspende la clave de API sin eliminarla. Puede volver a habilitarla en cualquier momento.
  • Restablecer (no compatible en la región EE. UU. (Virginia)): Genera un nuevo valor de clave. La clave anterior deja de ser válida inmediatamente.
Si requiere colaboración en equipo o asignación de costos, considere lo siguiente:
  • Espacio de trabajo: Un espacio de trabajo se utiliza para aislar recursos y permisos para diferentes proyectos o equipos. Para controlar qué modelos puede llamar un grupo de usuarios o para asignar costos a las llamadas de modelos, cree o seleccione un subespacio de trabajo de la lista.
Para obtener más información, consulte Permisos de claves de API y Consultar facturas y gestionar costos.

Configurar la clave de API como variable de entorno

Recomendamos configurar su clave de API como una variable de entorno. Esto le ayuda a evitar codificar la clave directamente en su código fuente, reduciendo el riesgo de exposición accidental.
  • Linux
  • macOS
  • Windows
  • Permanente
  • Temporal
Para que la clave de API esté disponible en todas las nuevas sesiones del usuario actual, configúrela como una variable de entorno permanente.
  1. Ejecute el siguiente comando para agregar la configuración de la variable de entorno al archivo ~/.bashrc.
# Replace YOUR_DASHSCOPE_API_KEY with your DashScope API key
echo "export DASHSCOPE_API_KEY='YOUR_DASHSCOPE_API_KEY'" >> ~/.bashrc
Alternativamente, puede editar manualmente el archivo ~/.bashrc.
Ejecute el siguiente comando para abrir el archivo ~/.bashrc.
nano ~/.bashrc
Agregue el siguiente contenido al archivo de configuración.
# Replace YOUR_DASHSCOPE_API_KEY with your DashScope API key
export DASHSCOPE_API_KEY="YOUR_DASHSCOPE_API_KEY"
En el editor nano, presione Ctrl+X, luego Y y luego Enter para guardar y cerrar el archivo.
  1. Ejecute el siguiente comando para aplicar los cambios.
source ~/.bashrc
  1. Abra una nueva ventana de terminal y ejecute el siguiente comando para verificar que la variable de entorno esté configurada.
echo $DASHSCOPE_API_KEY

Uso de una clave API

Cuando llama a un modelo desde código o una herramienta de terceros, además de la clave de API, debe especificar un endpoint de servicio (el API Host que se muestra en el cuadro de diálogo de creación exitosa, que corresponde al base_url en su SDK o solicitud HTTP). Model Studio proporciona interfaces de protocolo compatibles con OpenAI y compatibles con Anthropic. El base_url difiere entre los dos protocolos y varía según la región. Consulte la documentación del protocolo que utiliza: No exponga su clave API.

Actualización de seguridad de claves de API

Model Studio ha actualizado el mecanismo de generación y almacenamiento de claves de API de pago por uso para mejorar la seguridad (excepto en la región EE. UU. (Virginia)). Las claves de API creadas antes de la actualización que comienzan con sk- siguen siendo totalmente funcionales y no se ven afectadas. Todas las claves de API creadas después de la actualización comienzan con sk-ws. La siguiente tabla describe las principales diferencias entre las claves de API creadas antes y después de la actualización.

Elemento de comparación

Claves anteriores a la actualización

Claves posteriores a la actualización

Formato de clave

Comienza con sk- y tiene aproximadamente 32 caracteres de longitud.

Comienza con sk-ws y es más larga que el formato anterior.

Visualización en texto sin formato

Puede copiar la clave completa en texto sin formato desde la consola en cualquier momento.

La clave en texto plano se muestra solo una vez al crearla. No se puede volver a ver después de cerrar el cuadro de diálogo. Si la pierde, restablézcala o cree una nueva clave.

Capacidad de invocación

Se puede utilizar para invocar modelos normalmente; la funcionalidad no se ve afectada.

Se puede utilizar para invocar modelos normalmente; la funcionalidad es idéntica a la de las claves anteriores a la actualización.

Acción recomendada

Le recomendamos que cree una nueva clave para reemplazar la antigua y mejorar la seguridad.

Copie y guarde la clave inmediatamente después de crearla, y almacénela de forma segura.

Gestionar claves de API a través de la API

Además de las operaciones de la consola, Alibaba Cloud Model Studio proporciona operaciones de OpenAPI que le permiten crear, consultar, editar, eliminar, habilitar, deshabilitar y restablecer claves de API mediante programación, para que pueda integrar la gestión de claves de API en flujos de trabajo automatizados. La llamada a las siguientes operaciones requiere autenticación de firma con la AccessKey de su cuenta de Alibaba Cloud (no la propia clave de API) y los permisos de RAM correspondientes. Puede depurar cada operación en línea en el portal para desarrolladores de OpenAPI o llamarla a través de un SDK de Alibaba Cloud.

Operación

Descripción

CreateApiKey

Crea una clave API.

GetApiKey

Consulta la información de una clave API específica.

ListApiKeys

Consulta la lista de claves API.

UpdateApiKey

Edita una clave API, como su descripción y configuración de permisos.

DeleteApiKey

Elimina una clave API. Esta operación no se puede deshacer.

EnableApiKey

Habilita una clave API (no compatible con la región EE. UU. (Virginia)).

DisableApiKey

Deshabilita una clave de API. La clave se conserva y puede volver a habilitarse en cualquier momento (no compatible en la región EE. UU. (Virginia)).

ResetApiKey

Restablece una clave de API. Se genera un nuevo valor de clave y la clave anterior deja de ser válida inmediatamente (no compatible en la región EE. UU. (Virginia)).

Permisos de clave API

Los permisos de una clave de API están determinados completamente por su espacio de trabajo. Todas las claves de API dentro del mismo espacio de trabajo tienen permisos idénticos. No necesita crear diferentes claves de API para distintos modelos, como modelos de texto a texto, de texto a imagen o de síntesis de voz.
  • Clave de API en el espacio de trabajo predeterminado: Puede llamar a todos los modelos estándar y a cualquier aplicación dentro del espacio de trabajo predeterminado.
  • Clave de API en un subespacio de trabajo: Puede llamar a modelos estándar autorizados para el subespacio de trabajo y a cualquier aplicación dentro de ese subespacio de trabajo.
Llamada a unmodelo ajustado: Después de ajustar e implementar un modelo en Alibaba Cloud Model Studio, solo una clave de API del espacio de trabajo del modelo puede llamarlo. No se requiere autorización por separado. Cuando Create API Key o hace clic en Edit para una clave de API existente, puede cambiar los Permissions a Personalizado y configurar lo siguiente:
  • Lista blanca de direcciones IP: Permite que solo las direcciones IP en la lista blanca usen la clave de API para realizar llamadas (admite direcciones IPv4 y bloques CIDR; IPv6 solo es compatible en la región China (Beijing), y la región EE. UU. (Virginia) solo admite IPv4).
  • Ámbito de acceso: Seleccione los modelos o aplicaciones específicos a los que esta clave de API puede acceder. La clave no puede llamar a recursos no seleccionados. Puede seleccionar hasta 30 modelos.

Validez de la clave API

Las claves API no caducan. Permanecen válidas hasta que las elimine manualmente. Para otorgar acceso temporal a aplicaciones o usuarios de terceros, o para controlar estrictamente operaciones de alto riesgo como acceder o eliminar datos sensibles, puede generar una clave de API temporal (válida por hasta 1800 segundos). Esto evita exponer una clave de API a largo plazo y reduce el riesgo de filtraciones.

Códigos de error

Si una llamada al modelo falla y devuelve un mensaje de error, consulte Códigos de error para solucionar el problema.

FAQ

P: ¿Cuántas claves API puedo crear bajo una sola cuenta de Alibaba Cloud? R: Cada cuenta de Alibaba Cloud puede crear hasta 10 espacios de trabajo (incluido el espacio de trabajo predeterminado), y cada espacio de trabajo puede tener hasta 20 claves de API. P: ¿Siguen siendo válidas las claves API creadas por un usuario RAM después de eliminar al usuario? R: Depende de cuándo se crearon las claves de API. Si elimina un usuario RAM en la consola RAM, las claves de API que el usuario creó antes del 25 de marzo de 2026 se eliminan y ya no se pueden usar para llamadas a modelos. Las claves de API creadas el 25 de marzo de 2026 o después no se eliminan y siguen siendo válidas para llamadas a modelos. P: Usé elechocomando y confirmé que la variable de entorno estaba configurada correctamente. ¿Por qué mi código sigue indicando que no se encuentra la clave de API? R: Esto puede ocurrir por las siguientes razones:
  • Escenario 1: Se configuró una variable de entorno temporal. Una variable temporal solo es válida dentro de la sesión de terminal actual y no afecta a los IDE en ejecución u otras aplicaciones. Consulte las instrucciones en este tema para configurar una variable de entorno permanente.
  • Escenario 2: El IDE, la herramienta de línea de comandos o la aplicación no se reiniciaron.
    • Debe reiniciar su IDE (como VS Code) o terminal para cargar las nuevas variables de entorno.
    • Si configura la variable de entorno después de implementar una aplicación, debe reiniciar el servicio de la aplicación para volver a cargar las variables de entorno.
  • Escenario 3: La variable falta en un archivo de configuración del servicio. Si su aplicación es iniciada por un administrador de servicios, como systemd o supervisord, es posible que deba agregar la variable de entorno al archivo de configuración del administrador de servicios.
  • Escenario 4: Uso delsudocomando. Si usa sudo python xx.py para ejecutar el script, es posible que las variables de entorno del usuario actual no se hereden. Esto se debe a que sudo no hereda todas las variables de entorno de forma predeterminada. Puede usar el comando sudo -E python xx.py, donde el parámetro -E asegura que las variables de entorno se pasen. Si tiene permiso para ejecutar el script, puede ejecutar python xx.py directamente.