Crear un API Key (Token)

En MoleAPI, API Key también suele llamarse token. Es la credencial de identidad que utilizas al invocar la API y normalmente aparece con el formato sk-....

Una vez creado, puedes usarlo en Chatbox, NextChat, Immersive Translate, OpenAI SDK u otras herramientas compatibles con interfaces OpenAI personalizadas.

Qué necesitas preparar antes de crearlo

Antes de empezar, se recomienda confirmar lo siguiente:

1. Tu cuenta ya está registrada y puedes iniciar sesión en la consola de MoleAPI.
2. La cuenta dispone de saldo disponible o, al menos, de la quota de prueba para nuevos usuarios.
3. Ya tienes claro para qué se usará este Key, por ejemplo:
   • Pruebas diarias
   • Desarrollo local
   • Un proyecto en producción
   • Una aplicación independiente dentro del equipo

Paso 1: acceder a la página de gestión de KEY

Después de iniciar sesión, entra en la página KEY 管理 desde la barra lateral izquierda de la consola:

• Ruta: 控制台 → KEY 管理
• Acceso directo: https://home.moleapi.com/console/token

Una vez dentro, haz clic en 添加令牌 en la parte superior.

Paso 2: completar el formulario de creación

Tras hacer clic, se abrirá el cuadro de diálogo «创建新的令牌». La siguiente imagen está basada en la interfaz real de la consola de MoleAPI:

Si por ahora solo quieres crear el Key sin entender todos los campos de una vez, puedes centrarte primero en estos 4 aspectos más importantes:

• Nombre: para identificar fácilmente su uso más adelante
• Grupo de token: determina por qué grupo de modelos pasará este Key
• Fecha de expiración: determina cuánto tiempo permanecerá activo este Key
• Restricciones de modelo: si no estás seguro, en la primera creación puedes dejarlo sin restricciones

A continuación se explican uno por uno en ese orden.

1) Nombre (obligatorio)

Es el nombre descriptivo que tú mismo asignas a este Key para diferenciar su uso.

Convenciones recomendadas:

• dev-local
• chatbox-test
• nextchat-prod
• openclaw-docs

Se recomienda que el nombre sea autoexplicativo, para que luego resulte más fácil localizarlo en los logs de uso, la gestión de Key y el control de quota.

2) Grupo de token

Este campo sirve para determinar por qué grupo se enruta el token.

Normalmente, el grupo afecta a:

• El rango de modelos disponibles
• La estrategia de precios
• La estabilidad del channel o la fuente de suministro

Si es la primera vez que lo creas, puedes usar primero el grupo predeterminado. Cuando ya conozcas mejor la plataforma, podrás cambiar a un grupo más adecuado según el precio, la disponibilidad de modelos y el uso de negocio.

3) Fecha de expiración (obligatorio)

MoleAPI permite seleccionar manualmente la fecha de expiración y también ofrece varios accesos rápidos:

• 永不过期
• 一个月
• 一天
• 一小时

Cómo elegir la opción más adecuada:

• Pruebas temporales: se recomienda 一天 o 一小时
• Desarrollo local: se recomienda 一个月
• Servicios estables a largo plazo: puedes elegir 永不过期, pero conviene combinarlo con quota y políticas de seguridad

Para principiantes, si solo quieres verificar que la API funciona correctamente, se recomienda crear primero un Key de corta duración y, una vez confirmado, crear después el Key definitivo.

4) Cantidad a crear (obligatorio)

El valor predeterminado es 1, lo que significa que solo se crea un token.

Si necesitas distribuir Keys independientes de una sola vez para varios entornos o varios miembros, puedes crear varios en lote. En ese caso, el sistema añadirá un sufijo aleatorio al nombre para facilitar la diferenciación.

Si es tu primera vez, puedes dejarlo en 1.

5) Quota

Aquí puedes establecer el límite de quota disponible para un único token.

Ten en cuenta lo siguiente:

• Este es el límite de quota propio del token, no el saldo total de la cuenta.
• Aunque aquí configures un valor alto, el consumo real seguirá estando limitado por el saldo restante de la cuenta.

Si quieres que este Key solo se utilice para pruebas a pequeña escala, puedes asignarle una quota baja para evitar usos accidentales.

6) Quota ilimitada

Normalmente viene activada por defecto.

Cuando está activada, este token no tiene un límite de quota independiente y solo queda restringido por el saldo de la cuenta.

Se puede entender así:

• Key de prueba temporal: puedes desactivar la quota ilimitada y asignar una quota pequeña
• Key de servicio en producción: activarla o no depende de tu estrategia de control de riesgos

Si eres especialmente sensible al control de riesgos, se recomienda no activar quota ilimitada en todos los Keys.

7) Lista de restricciones de modelos

Aquí puedes restringir qué modelos puede invocar este Key.

Si no estableces restricciones, normalmente significa que podrá invocar todos los modelos permitidos dentro del grupo actual.

Prácticas recomendadas:

• Uso de prueba: puedes dejarlo sin restricciones al principio para explorar
• Proyecto en producción: habilita solo los modelos realmente necesarios para el negocio
• Trabajo en equipo: usa distintos Keys para distintos sistemas y restringe el rango de modelos

Las ventajas de hacerlo así son:

• Evitar llamadas accidentales a modelos caros
• Reducir el riesgo derivado de permisos excesivos
• Facilitar el análisis de logs y del origen de costes

8) Lista blanca de IP

Aquí puedes indicar las IP autorizadas para acceder a este Key; se admiten expresiones CIDR.

Si no rellenas este campo, por defecto no habrá restricción por IP de origen.

Escenarios adecuados para activar una lista blanca de IP:

• El servidor está desplegado en una máquina con IP fija
• La empresa dispone de una IP de salida fija
• Quieres que un Key de producción solo pueda invocarse desde un entorno concreto

Si todavía estás en fase de depuración local y no dispones de una IP de salida fija, puedes dejarlo en blanco por ahora y completarlo más adelante.

Paso 3: enviar y copiar el API Key

Una vez verificado todo, haz clic en 提交 en la esquina inferior derecha.

Cuando la creación se complete correctamente, verás el nuevo token en la lista de KEY 管理. A continuación, realiza de inmediato estas dos acciones:

1. Copia el API Key completo
2. Guárdalo en un lugar seguro, por ejemplo:
   • Un gestor de contraseñas local
   • Variables de entorno
   • Un sistema de gestión de secretos del servidor

Configuración recomendada para principiantes

Si solo quieres poner en marcha MoleAPI rápidamente, se recomienda crear el Key así:

• Nombre: dev-local
• Grupo de token: grupo predeterminado
• Fecha de expiración: un mes
• Cantidad a crear: 1
• Quota: establece una quota de prueba que te resulte aceptable, o activa primero la quota ilimitada
• Restricciones de modelo: sin restricciones por ahora
• Lista blanca de IP: dejar en blanco por ahora

Esta configuración es la más fácil para empezar correctamente; más adelante ya podrás ir restringiendo permisos de forma progresiva.

Qué hacer después de crearlo

Después de obtener el API Key, normalmente todavía necesitas dos datos más para empezar a invocar la API de verdad:

• Base URL: https://api.moleapi.com/v1
• API Key: el sk-... que acabas de crear

Se recomienda seguir leyendo:

• ¿Qué es un API Key?
• ¿Qué es Base URL?
• ¿Qué son los grupos de channel?
• Configuración de seguridad del API Key

Preguntas frecuentes

¿Por qué he creado el Key, pero la llamada sigue fallando?

Las causas más comunes son:

• La Base URL es incorrecta o falta /v1
• El nombre del modelo es incorrecto
• La cuenta no tiene saldo suficiente
• El modelo no está soportado en el grupo de token
• El token tiene configuradas restricciones de modelo o de IP

¿Se pueden crear varios API Key con una misma cuenta?

Sí. Se recomienda separar varios Keys por uso, en lugar de compartir uno solo entre todos los proyectos.

¿Conviene usar el mismo Key para pruebas y producción?

No se recomienda. Lo más recomendable es:

• Un Key de prueba
• Un Key para el entorno de producción
• Si es necesario, dividirlos aún más por proyecto

Así será más seguro y también más fácil controlar costes y diagnosticar problemas.