Claves API#

Las claves API de Ultralytics Platform permiten un acceso programático seguro para el entrenamiento remoto, la inferencia y la automatización. Crea claves con nombre utilizando cifrado AES-256-GCM para diferentes casos de uso.

Crear clave de API#

Crea una nueva clave API:

1. Ve a Settings > API Keys
2. Haz clic en Create Key
3. Introduce un nombre para la clave (por ejemplo, "Training Server")
4. Haz clic en Create Key

Nombre de la clave#

Dale a tu clave un nombre descriptivo:

• training-server - Para máquinas de entrenamiento remoto
• ci-pipeline - Para integración CI/CD
• local-dev - Para desarrollo local

Visualización de la clave#

Tras la creación, la clave se muestra en un diálogo de confirmación:

Formato de la clave#

Las claves API siguen este formato:

ul_a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4

• Prefijo: ul_ identifica las claves de Ultralytics
• Cuerpo: 40 caracteres hexadecimales aleatorios
• Total: 43 caracteres

Seguridad de la clave#

• Las claves se almacenan con cifrado AES-256-GCM
• La autenticación utiliza un hash SHA-256 para una búsqueda indexada rápida
• Los valores completos de las claves nunca se almacenan en texto plano

Uso de claves API#

Variable de entorno#

Define tu clave como una variable de entorno:

export ULTRALYTICS_API_KEY="YOUR_API_KEY"

YOLO CLI#

Valida y guarda la clave usando el YOLO CLI:

yolo login YOUR_API_KEY

Elimina la clave guardada con yolo logout.

Cabeceras HTTP#

Incluye la clave en las solicitudes API:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://platform.ultralytics.com/api/...

Consulta la referencia de la REST API para ver todos los puntos de conexión disponibles.

Entrenamiento remoto#

Habilita la transmisión de métricas con tu clave.

Instala o actualiza el paquete Ultralytics antes de empezar:

pip install -U ultralytics

export ULTRALYTICS_API_KEY="YOUR_API_KEY"
yolo train model=yolo26n.pt data=coco.yaml project=username/project name=exp1

Consulta Cloud Training para obtener la guía completa de entrenamiento remoto.

Gestionar claves#

Ver claves#

Todas las claves aparecen en la pestaña Settings > API Keys:

Cada tarjeta de clave muestra el nombre de la clave, el valor de la clave copiable, el tiempo de creación relativo, el recuento de uso y un botón de revocación.

Revocar clave#

Revoca una clave si está comprometida o ya no es necesaria:

1. Busca la clave en la sección de claves API
2. Haz clic en el botón Revocar (papelera)
3. Confirma la revocación

Regenerar clave#

Si una clave está comprometida:

1. Crea una nueva clave con el mismo nombre
2. Actualiza tus aplicaciones
3. Revoca la clave antigua

Claves API del espacio de trabajo#

Las claves API están limitadas al espacio de trabajo activo actualmente:

• Espacio de trabajo personal: Las claves se autentican como tu cuenta personal
• Espacio de trabajo de equipo: Las claves se autentican dentro del contexto del equipo

Al cambiar de espacio de trabajo en la barra lateral, la sección de claves API muestra las claves para ese espacio de trabajo. Se requiere un rol de Editor o superior para gestionar las claves API del espacio de trabajo. Consulta Teams para obtener detalles sobre los roles.

Buenas prácticas de seguridad#

Haz lo siguiente#

• Almacena las claves en variables de entorno
• Utiliza claves separadas para diferentes entornos
• Revoca las claves no utilizadas rápidamente
• Rota las claves periódicamente
• Utiliza nombres descriptivos para identificar el propósito de cada clave

No hagas lo siguiente#

• Confirma las claves en el control de versiones
• Comparte claves entre aplicaciones
• Registra las claves en la salida de la aplicación
• Inserta claves en código del lado del cliente

Rotación de claves#

Rota las claves periódicamente por seguridad:

1. Crea una nueva clave con el mismo nombre
2. Actualiza las aplicaciones para usar la nueva clave
3. Verifica que las aplicaciones funcionen correctamente
4. Revoca la clave antigua

Solución de problemas#

Error de clave no válida#

Error: Invalid API key

Soluciones:

1. Verifica que la clave se haya copiado correctamente (incluyendo el prefijo ul_)
2. Comprueba que la clave no haya sido revocada
3. Confirma que la variable de entorno esté definida
4. Asegúrate de que estás usando ultralytics>=8.4.104

Permiso denegado#

Error: Permission denied for this operation

Soluciones:

1. Verifica que eres el propietario del recurso o que tienes el acceso apropiado al espacio de trabajo
2. Comprueba que la clave pertenezca al espacio de trabajo correcto
3. Crea una nueva clave si es necesario

Límite de frecuencia superado (Rate Limited)#

Error: Rate limit exceeded

Soluciones:

1. Reduce la frecuencia de las solicitudes; consulta la tabla de límites de frecuencia para ver los límites por punto de conexión
2. Implementa un retroceso exponencial utilizando la cabecera Retry-After
3. Usa un endpoint dedicado cuando necesites capacidad de inferencia aislada

FAQ#

¿Cuántas claves puedo crear?#

No existe un límite estricto para las claves API. Crea tantas como necesites para diferentes aplicaciones y entornos.

¿Caducan las claves?#

Las claves no caducan automáticamente. Permanecen válidas hasta que se revocan. Considera implementar la rotación por seguridad.

¿Puedo ver mi clave después de crearla?#

Sí, los valores completos de las claves son visibles en la lista de claves en Settings > API Keys. La plataforma descifra y muestra tus claves para que puedas copiarlas en cualquier momento.

¿Las claves son específicas de una región?#

Las claves funcionan en todas las regiones, pero solo acceden a los datos de la región de tu cuenta.

¿Puedo compartir las claves con los miembros del equipo?#

Mejor práctica: haz que cada miembro del equipo cree su propia clave. Para los espacios de trabajo de equipo, cada miembro con rol de Editor o superior puede crear claves limitadas a ese espacio de trabajo.