Claves API#

Las claves de API de Ultralytics Platform permiten un acceso programático seguro para el entrenamiento remoto, la inferencia y la automatización. Crea claves con nombre con 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 la integración de 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 keys se almacenan con cifrado AES-256-GCM, nunca en texto plano
• Los primeros 11 caracteres (ul_ más 8 caracteres hexadecimales) actúan como un prefijo de visualización, por lo que se puede identificar una key sin exponerla

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/...

O pásalo al Python SDK (pip install "ultralytics-platform>=0.1.5"), que también lee ULTRALYTICS_API_KEY:

from ultralytics_platform import Platform

client = Platform(api_key="YOUR_API_KEY")

Consulta la REST API Reference 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 ver la guía completa de entrenamiento remoto.

Gestionar claves#

Ver claves#

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

Cada tarjeta de key muestra el nombre de la key, el valor de la key copiable, el tiempo relativo de creación 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 keys se autentican como el propietario del espacio de trabajo de equipo, con permisos completos de propietario en ese espacio de trabajo

Al cambiar de espacio de trabajo en la barra lateral, la sección API Keys muestra las keys para ese espacio de trabajo. Debido a que una key de espacio de trabajo conlleva permisos de propietario, solo el propietario del espacio de trabajo puede crear, ver o revocar una. Consulta Teams para obtener detalles sobre los roles.

On Premise Worker Keys#

Conectar un host On Premise genera una worker key independiente. Las worker keys se gestionan desde la integración On Premise en lugar de esta pestaña, nunca aparecen en la lista junto con tus API keys, y se revokan desconectando el host, lo que también cancela los trabajos en cola y en ejecución de ese host.

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 copie correctamente (incluido 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 estar usando ultralytics>=8.4.120

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. Si estás gestionando keys en un espacio de trabajo de equipo, confirma que eres el propietario del espacio de trabajo; otros roles obtienen Workspace owner access required
4. Crea una nueva clave si es necesario

Límite de frecuencia superado (Rate Limited)#

Error: Rate limit exceeded

Soluciones:

1. Reduce la frecuencia de solicitudes; consulta la rate limit table para conocer los límites por categoría
2. Implementa un retroceso exponencial usando la cabecera Retry-After
3. Usa un dedicated endpoint cuando necesites capacidad de inferencia aislada

FAQ#