Una Qwen API Key es la credencial que permite llamar a los modelos Qwen. No se trata solo de una cadena de caracteres: de su tipo y de a qué pertenece dependen la autenticación de las solicitudes, la cuenta a la que se cargan los costos y la facilidad para diagnosticar problemas. En Qwen, la clave está vinculada además a dos elementos —la región y el espacio de trabajo—, y de ahí nace la causa más común de los errores 401 con una clave que «está bien escrita».

Este artículo sigue el orden «entender la pertenencia → crear → configurar permisos → guardar la variable → diagnosticar → rotar» para explicar las dos rutas: la oficial de Alibaba Cloud Model Studio y la de ZSQH AI Gateway.

Nota: Qwen, Tongyi Qianwen, Alibaba Cloud, Model Studio (Bailian) y DashScope son marcas comerciales o nombres de producto del Grupo Alibaba y sus empresas vinculadas. Este artículo solo tiene fines técnicos y no implica relación de subordinación, agencia ni autorización con el Grupo Alibaba. Los canales de creación, las reglas de permisos y la facturación se rigen por la documentación y la consola oficiales de Alibaba Cloud Model Studio.

1. Primero, entiende las tres dimensiones de una clave

En Model Studio, una clave pertenece simultáneamente a tres dimensiones:

  • Cuenta: puede ser la cuenta principal de Alibaba Cloud o un usuario RAM.
  • Región: Pekín, Singapur, Virginia (EE. UU.), Hong Kong de China y otras regiones son independientes entre sí.
  • Espacio de trabajo: el espacio predeterminado o un subespacio; determina qué modelos puede llamar la clave.

Si cualquiera de estas tres dimensiones no coincide, el resultado será un fallo de autenticación o permisos insuficientes. La región es especialmente importante: cada región tiene su propio dominio de acceso, sus API Keys y su lista de modelos, y una clave no se puede usar en otra región. Una clave creada en Pekín que se envía a la dirección de Singapur suele devolver 401 e invalid_api_key, pero eso no significa que la clave haya dejado de ser válida.

2. Crear una API Key en Alibaba Cloud Model Studio

La ruta oficial es adecuada para equipos que solo usan Qwen y quieren acceder cuanto antes a los modelos y capacidades nuevos. Los pasos básicos son:

  1. Inicia sesión en la consola de Alibaba Cloud Model Studio y selecciona la región correcta en la esquina superior derecha.
  2. Entra en la página API Key y haz clic en «Create API Key».
  3. Elige la cuenta propietaria: por defecto, la cuenta principal de Alibaba Cloud; también puedes indicar un usuario RAM.
  4. Elige el espacio de trabajo propietario: el espacio predeterminado sirve para empezar rápido; si necesitas aislar modelos o costos, usa un subespacio.
  5. Configura los permisos: se recomienda empezar con «All»; si hace falta restringir, elige «Custom» y define la lista blanca de IP y el alcance de modelos accesibles.
  6. Al terminar, copia de inmediato la clave completa y el API Host que muestra la página, y guárdalos en un gestor de contraseñas o en un sistema de secretos del servidor.
  7. Valida con una solicitud mínima que la autenticación, la región y el nombre del modelo son correctos antes de pasar a la configuración de producción.

Hay dos detalles que suelen pasarse por alto. Primero, para crear una clave se necesitan permisos de superadministrador o de administrador del espacio de trabajo; es posible que un miembro normal no vea el botón de creación. Segundo, la clave en texto plano normalmente se muestra completa una sola vez, al crearla; después de cerrar el cuadro de diálogo no se puede volver a consultar. Si no la guardaste, solo queda restablecerla o crear otra. Las claves de larga duración no caducan automáticamente, pero «no caducar» no equivale a «no rotar».

3. Espacios de trabajo, RAM y límites de permisos

El espacio de trabajo es el núcleo del modelo de permisos de Model Studio. Una clave del espacio predeterminado puede llamar a los modelos estándar de ese espacio; una clave de un subespacio solo puede llamar a los modelos habilitados en ese subespacio. Si desplegaste un modelo ajustado, debes usar una clave del espacio de trabajo donde reside el modelo; de lo contrario, verás «el modelo existe pero no tienes acceso».

Las reglas sobre usuarios RAM requieren más atención:

  • Una clave puede pertenecer a un usuario RAM; el formato de cuenta suele ser username@<AccountAlias>.onaliyun.com.
  • Si eliminas ese usuario o rol en la consola RAM, sus claves dejan de funcionar de inmediato y no se pueden recuperar.
  • Si sacas al usuario RAM del espacio de trabajo, la clave deja de funcionar; al volver a añadirlo, vuelve a estar activa.

Los permisos personalizados son adecuados para producción: limita el origen con una lista blanca de IP y limita los modelos llamables con el alcance de modelos. La lista blanca admite IPv4 e IPv6, pero por ahora IPv6 solo está disponible en la región de Pekín; la región de EE. UU. solo admite IPv4. El límite de entradas se rige por la consola. Las claves de paquete (por ejemplo, las que empiezan por sk-sp-) pertenecen a otro sistema distinto del de las API Keys generales; no uses una clave de paquete con una Base URL general.

4. Guardar la clave en variables de entorno

La práctica más peligrosa es escribir la clave en el código fuente, en el bundle del frontend, en la salida de un notebook o en un chat. La variable de entorno convenida por Model Studio es DASHSCOPE_API_KEY; el código solo hace referencia al nombre de la variable:

# Archivo .env local; recuerda añadirlo a .gitignore
DASHSCOPE_API_KEY=your_key_here

# Vigente solo en la terminal actual
export DASHSCOPE_API_KEY="your_key_here"

# Verificación mínima: confirma que clave, región y nombre del modelo coinciden
curl https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"qwen3.8-max","messages":[{"role":"user","content":"ping"}]}'

En producción, como mínimo: no subir .env a Git; usar Secret Manager, KMS o secretos de contenedor del proveedor cloud; usar variables independientes en CI/CD; enmascarar la cabecera Authorization en los registros; y no mantener nunca una clave de servidor en el frontend. Cabe señalar que los nombres de modelo y los precios de los ejemplos cambian con las versiones; los nombres reales y la facturación se rigen por la lista de modelos de la consola y la página de precios de modelos.

5. Clave oficial o clave del gateway: cómo elegir

Si el equipo solo usa Qwen, la clave oficial es la opción más directa. Si además usa Qwen, DeepSeek, GLM, Kimi y otros modelos, o quiere unificar cuotas, facturas y comprobantes, puedes crear una clave en ZSQH AI Gateway. No son alternativas excluyentes, sino dos formas de gestionar el acceso.

Dimensión Clave oficial de Alibaba Cloud Model Studio Clave de ZSQH AI Gateway
Entrada de creación Consola de Model Studio Consola del gateway
Alcance Modelos Qwen y de terceros dentro de la región de Model Studio Varios modelos habilitados en el gateway
Cuenta de facturación Cuenta de Alibaba Cloud Cuenta del gateway
Base URL dashscope.aliyuncs.com y otras direcciones de Model Studio https://ai.zhongshangqihang.com/v1
Casos adecuados Solo Qwen y acceso a los modelos más recientes Acceso y facturación unificados para varios modelos

Los dos tipos de clave usan sistemas de autenticación distintos y no se pueden mezclar: la clave oficial va con la Base URL oficial y la del gateway con la Base URL del gateway. La mezcla suele manifestarse como un 401 y, en segundo lugar, como una solicitud enviada a la región o al servicio equivocados.

6. Diagnóstico de 401: primero la región, luego las cabeceras

Ante un 401, no reinstales el SDK a la ligera. Sigue este orden:

  1. Comprueba que la cabecera sea Authorization: Bearer <key> y que después de Bearer haya exactamente un espacio.
  2. Verifica que la clave esté completa, sin saltos de línea, comillas ni espacios al principio o al final.
  3. Confirma que la región donde se creó la clave coincide con la región de la Base URL.
  4. Comprueba que el espacio de trabajo coincida; el dominio exclusivo de un espacio solo acepta las claves de ese espacio.
  5. Revisa si la clave fue deshabilitada, eliminada o restablecida, y si el usuario RAM creador fue retirado del espacio o eliminado.
  6. Descarta que se esté usando una clave de paquete que empieza por sk-sp- en una interfaz general.
  7. Comprueba si la cuenta tiene deudas. El impago suele devolver 400 y Arrearage, no 401, pero también se percibe como «no puedo llamar».

Si todo lo anterior es correcto, registra el Request ID de la respuesta y búscalo en los registros de llamadas o en el monitoreo de modelos de la consola. El Request ID es el dato más útil al abrir un ticket, mucho más que un simple «da error».

7. Rotación, revocación y auditoría

Una sola clave para todo ahorra trabajo a corto plazo, pero complica el diagnóstico a largo plazo. Se recomienda separar al menos por entorno y servicio: una para pruebas, una para producción y una para CI/CD; una por cada servicio backend; y nombres de clave con entorno y servicio, por ejemplo prod-customer-service. Añade límites de cuota y alertas de consumo para detectar llamadas anómalas antes de que consuman una gran cantidad de crédito.

Al rotar, no elimines directamente la clave antigua. El orden correcto es: crear la nueva clave → desviar poco a poco una parte del tráfico → confirmar que los permisos de modelo, la cuota y la facturación funcionan → revocar la clave antigua. Así puedes revertir rápido si la nueva configuración falla. Si un miembro del equipo deja la empresa, si se transfiere trabajo a un externalizado o si una clave apareció en registros o en un repositorio público, revócala y créala de nuevo de inmediato; además, revisa la facturación y los registros de llamadas por si hay consumo anómalo.

8. Preguntas frecuentes (FAQ)

1. ¿Dónde se crea una Qwen API Key?

Inicia sesión en la consola de Alibaba Cloud Model Studio, selecciona la región y entra en la página API Key para crearla. Si usas ZSQH AI Gateway, se crea en la consola del gateway. Las dos claves no son intercambiables.

2. ¿Por qué una clave válida devuelve 401?

La causa más común es una región que no coincide; después, una clave copiada de forma incompleta, un formato de cabecera incorrecto, un espacio de trabajo que no coincide o un usuario RAM creador que ya fue eliminado. Primero verifica que la clave y la Base URL pertenezcan a la misma región; luego revisa las cabeceras.

3. ¿Se puede compartir una clave entre varios proyectos?

Técnicamente sí, pero no se recomienda. Una clave compartida no permite distinguir el origen de las llamadas; una filtración afecta a todo el negocio y la facturación es difícil de repartir. Como mínimo, separa por entorno y por servicio principal.

4. ¿Qué hago si se filtra una clave?

Deshabilita o elimina la clave en la consola de inmediato, crea una nueva y actualiza la configuración del servidor. Revisa la facturación y los registros de llamadas para confirmar si hubo consumo anómalo y, si es necesario, contacta al soporte de la plataforma para explicar la situación. No basta con cambiar el código: hay que revocar la clave antigua.

5. ¿Se pueden mezclar la clave oficial y la del gateway?

No. Los sistemas de autenticación, las Base URL y las cuentas de facturación son distintos. Mezclarlas suele producir un 401 y también puede enviar solicitudes a la dirección de servicio equivocada.

Lecturas relacionadas